textstat, a Python library of readability formulas you call one at a time

Many formulas, one argument

Textstat is described as an easy to use library to calculate statistics from text, helping to determine readability, complexity and grade level. The API is deliberately flat. Every function takes the same argument, the text for which statistics need to be calculated, and returns one number. The usage example calls a long list of them on the same sample: flesch_reading_ease, flesch_kincaid_grade, smog_index, coleman_liau_index, automated_readability_index, dale_chall_readability_score, difficult_words, linsear_write_formula, gunning_fog, text_standard, fernandez_huerta, szigriszt_pazos, gutierrez_polini, crawford, gulpease_index and osman. There is no combined readability score and no default. If you want a single number for a dashboard, you have to choose which formula you are willing to defend, which is a decision the library refuses to make for you.

>>> import textstat

>>> textstat.flesch_reading_ease(test_data)
>>> textstat.flesch_kincaid_grade(test_data)
>>> textstat.smog_index(test_data)
>>> textstat.gunning_fog(test_data)
>>> textstat.text_standard(test_data)

What the numbers mean, and the scale you get back

The documentation explains each formula's output in terms of a grade level, and the Flesch Reading Ease comes with a scale table. A score of 90 to 100 is very easy, 80 to 89 easy, 70 to 79 fairly easy, 60 to 69 standard, 50 to 59 fairly difficult, 30 to 49 difficult, and 0 to 29 very confusing. The table is described as an example of values, and the note underneath is the part that matters in practice: while the maximum score is 121.22, there is no limit on how low the score can be, and a negative score is valid. The grade-level formulas share a reading convention, where a score of 9.3 means that a ninth grader would be able to read the document. The Automated Readability Index is described slightly differently, as outputting a number that approximates the grade level needed to comprehend the text, so 6.5 means the text is readable at 6th to 7th grade.

| Score |    Difficulty     |
|90-100 | Very Easy         |
| 80-89 | Easy              |
| 70-79 | Fairly Easy       |
| 60-69 | Standard          |
| 50-59 | Fairly Difficult  |
| 30-49 | Difficult         |
| 0-29  | Very Confusing    |

Text length is not a detail, it is a validity condition

The SMOG entry carries the warning that matters most in the whole library. Texts of fewer than 30 sentences are statistically invalid, because the SMOG formula was normed on 30-sentence samples, and textstat requires at least 3 sentences for a result. So the library will return a number where the underlying statistic has no meaning, and it tells you the floor it enforces rather than refusing to answer. This is worth internalising before you build a feature on top of it, because a readability score computed on a paragraph and a score computed on a chapter are the same function call and completely different quantities. The other formulas have their own sample assumptions, but the SMOG one is the one the documentation calls out, and a reader who is scoring short marketing copy or a single paragraph is the reader most likely to be misled.

Texts of fewer than 30 sentences are statistically invalid, because
the SMOG formula was normed on 30-sentence samples. textstat requires at
least 3 sentences for a result.

Language support, and the Spanish-specific formulas

By default the functions implement the algorithms for English. To change language you call set_lang with the language code, and the language is used for syllable calculation and to choose the variant of the formula. The table of which functions have which language variants shows flesch_reading_ease with coverage for en, de, es, fr, it, nl and ru, and gunning_fog with coverage for en and pl only. There is also a separate group of functions designed specifically for the Spanish language, which can be used on non-Spanish texts although that use is not recommended: fernandez_huerta, szigriszt_pazos, gutierrez_polini and crawford, and the documentation says additional information on the formula each implements is in its docstring. So the library's language story is two things rather than one: a set of English-first formulas with partial translation coverage, and a parallel set of Spanish-native formulas.

textstat.set_lang(lang)

How it is installed and what it pulls in

Installation is documented four ways, which is a small sign of the library's age. There is the standard pip install, the easy_install route, a clone of the GitHub repository followed by a pip install from the checkout, and a manual route that downloads the source tarball from the Python Package Index and runs setup.py build and setup.py install. The package metadata is more informative about the internals. The version is 0.7.13, the licence is MIT, and Python 3.6 or newer is required even though the classifiers list 3.9 through 3.13. The install_requires list has three entries, pyphen, nltk and setuptools, and the requirements file matches. pyphen is the hyphenation library, which is where the syllable and word splitting behaviour comes from, and nltk supplies the natural language toolkit resources that the difficult words function needs. The package data includes a file called easy_word_list, which is the vocabulary used for that calculation.

install_requires=["pyphen", "nltk", "setuptools"],
license="MIT",
python_requires=">=3.6",

The developer workflow, and what the repository holds

The repository is a straightforward setuptools package with a textstat/ package directory, a tests/ directory, a docs/ directory, a requirements.txt, a Pipfile and a Makefile. The Makefile shows the workflow: an install target that runs setup.py install, a test target that runs pytest through pipenv, a style target that runs flake8 with a max line length of 88, a clean target that removes the build artefacts and caches, and dist and upload targets that build a source distribution and a wheel and then upload them with twine. There is a local_test_workflow.py file at the root, which suggests a script for exercising the library locally outside the test suite, and a setup.cfg for the flake8 and other tool configuration. The releases are patch-level and frequent, with 0.7.13 from 2026-02-18, 0.7.12 from 2025-12-13 and 0.7.11 from 2025-11-08, and the last push to the repository was on 2026-10-13.

test:
	pipenv run pytest tests/

style:
	pipenv run flake8 . --exclude=build/,.venv --max-line-length=88

Where it fits, and the decision you have to make

The library does one thing well and refuses to make the hard call for you. For a writing tool that wants to show a reader how hard their text is, that is exactly right, because the formula choice is a product decision with a defensible answer and a wrong answer, and the library gives you every candidate. For a research pipeline the same flatness works, since you can compute several formulas and compare them. What the library does not do is tell you which one to believe, and the honest way to use it is to pick one and say so. Two checks before you ship. The first is sample size, because the difference between a 30-sentence sample and a 3-sentence one is the difference between a statistic and a number, and the SMOG caveat is the documented example of how that goes wrong. The second is language, because set_lang changes both the syllable counting and the formula variant, and a document left in the default English while being scored as German is a silent error the library will not catch.

The language will be used for syllable calculation and to choose
variant of the formula.

Editorial conclusion

Adopt textstat if you need to report readability numbers for a text pipeline, for example in an editor, a writing tool or a study, and skip it if you need a single authoritative score, because the library offers many formulas that disagree with each other and picking one is your decision. Verify three things before you wire it into a product: that you choose a formula deliberately, since the grade-level formulas agree in rough shape but not in output; that the text is long enough for the formula, because SMOG is statistically invalid below 30 sentences and textstat only requires 3; and that the language is set, since the default is English and the language choice changes both the syllable count and the formula variant.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. textstat/textstat on GitHub