Python typing grew through shared standards, competing implementations, better library annotations, and a lot of community collaboration. Explore how it developed, compare today's tools, and help shape what comes next.
Looking for package type coverage? This site used to measure annotation coverage across popular PyPI packages. That measurement is retired. For current numbers, use Joren's Typestats dashboard.
Our historical coverage data is preserved unchanged at its original locations, including the coverage trends and prioritized pages.
A Python annotation records what a name is expected to be. Nothing reads it at runtime by default; it is information for tools. Type checkers use it to find mistakes before the program runs, and editors use it for navigation, completion and refactoring.
Adoption is gradual by design. You can annotate one function, one module, or an entire package, and unannotated code keeps working. Python remains dynamically typed: annotations do not, on their own, enforce anything at runtime.
This is a curated path through two decades of work, not a list of every typing PEP. Four threads run through it: changes to the language, the tools that read annotations, the ecosystem that distributes them, and the governance that keeps them coherent.
PEP 3107 added a place to attach arbitrary expressions to function parameters and return values, deliberately without prescribing what they mean. Types were one suggested use among several. It was proposed in 2006 and the syntax shipped two years later in Python 3.0; the interpretation came later still.
Work began on pytype to bring static checking to Google's very large Python codebase. It took an inference-first approach: rather than requiring annotations, it inferred types and recorded them in separate interface files. This is when development started, not a public release.
Jukka Lehtosalo released the source of an experimental checker for a Python dialect with optional static types. The early prototype was not today's mypy, but it made the case that gradual typing could work in practice, and it shaped the standard that followed.
One shared vocabulary, so that a person, a checker and an editor
could all read the same annotation and agree on what it meant.
PEP 484 brought the typing module into the standard
library and gave static type checkers a shared interpretation of
annotations, while deliberately leaving their runtime meaning
unchanged.
Every checker needs to know the types of the standard library and of popular third-party packages. Rather than each tool maintaining its own copy, typeshed collects those stubs in one repository that the whole ecosystem contributes to and depends on, including teams who otherwise compete on checkers.
PEP 526 extended annotations past function signatures to variables, class attributes and module-level names, so a type could be stated where the value is defined instead of in a comment.
Meta released Pyre, a checker built for codebases large enough that incremental performance is a design constraint rather than an optimisation. This is its public-release milestone; work on it had been under way internally beforehand.
PEP 561 answered a practical question: how does a checker find
the types for a dependency you installed? A package ships a
py.typed marker with inline annotations, or ships
stubs, or a separate -stubs distribution provides
them. This is the machinery that decides whether your
dependencies are usefully typed for you.
Microsoft released Pyright, a checker designed to be fast enough to run continuously inside an editor. It tied checking closely to the editing experience, a pattern most later tools followed. Pyright the checker is distinct from the Pylance extension that builds on it.
PEP 544 gave duck typing a static form: a type can be defined by the methods an object has rather than by what it inherits from. It let the type system describe how Python is actually written.
A run of changes made ordinary annotations less noisy, which did
more for adoption than any single large feature:
list[str] instead of importing
List, X | None instead of
Optional[X], and Self for methods that
return their own class.
PEP 585 (built-in generics) in Python 3.9, PEP 604
(X | Y unions) in Python 3.10, and PEP 673
(Self) in Python 3.11.
PEP 695 introduced def f[T](x: T) -> T and the
type statement, so generics no longer required
declaring a TypeVar separately. It also defined a new
annotation scope and lazy evaluation for type aliases and type
parameter bounds and constraints.
With several independent checkers in wide use, "what does this annotation mean?" needed an answer that was not just one tool's behaviour. PEP 729 set up a council and made it responsible for the maintained typing specification and a conformance test suite that implementations can be measured against. This date is the PEP's resolution, not a membership announcement.
The first of the annual typed-Python surveys reported what people get out of typing and where it still hurts. Incomplete or incorrect types in third-party libraries came through as a recurring source of friction. See the survey section below.
Meta announced Pyrefly, a type checker and IDE experience written in Rust, building on lessons from its work on Pyre.
A Rust-based type checker and language server from the author of the Jedi language server, aiming at mypy-compatible behaviour.
ZubanLS went on to a beta release and was open-sourced later in 2025; the project blog tracks the sequence.
Google announced that pytype's new feature development is ending and that Python 3.12 is its final supported version, as investment shifts toward other approaches. The project's FAQ still allows for bug fixes. This is a wind-down of feature work, not a statement that the repository was archived or that all maintenance stopped that day.
pytype opened this timeline in 2012 and closes a chapter of it here. It was the most prominent inference-first checker: it aimed to be useful on code that had no annotations at all, where the rest of the ecosystem converged on reading annotations developers write. Neither approach is universally better, and the trade-off it explored has not gone away.
Astral's Rust-based type checker and language server moved to beta, having been introduced publicly earlier in 2025.
A second year of responses, and the same headline complaint: library types that are missing, incomplete or wrong. See the survey section below.
Pyrefly released version 1.0, its first stable release after the type checker and IDE experience entered public alpha in 2025.
Every entry above already happened. This one has not. Coding agents now read and write a lot of Python, and it is an open question how much the type system should be built for them as well as for people. Nobody has the answer yet, which is exactly why it belongs at the end of the story rather than in it. Read the open questions.
The timeline stops at what has actually happened. Where it goes next is genuinely undecided, and the community is still working out the answer.
Two annual surveys now ask Python developers how typing is working for them. Both are self-selected samples of people who chose to respond to a survey about typing, so read them as signal about that population, not as a measurement of all Python developers.
88% of respondents said they always or often use types Self-selected sample of survey respondents, not a measurement of all Python developers.
Respondents pointed to catching bugs earlier and to better editor support. The friction they reported was less about the language than about their dependencies.
86% of respondents said they always or often use type hints Self-selected sample of survey respondents, not a measurement of all Python developers. The two years are separate samples and should not be read as a trend line.
The same theme returned, more sharply: incomplete or incorrect annotations in third-party libraries, and a continuing request for better library coverage.
Not published yet. When the results are out, they will be linked here. Until then there is nothing to report: no preview numbers, no date.
You can annotate your own code carefully and still get little out of
it. The moment a call crosses into a dependency that ships no types,
or ships types that are wrong, the checker loses the thread. Values
become Any, errors stop being caught, and completion in
your editor goes quiet.
This is what both surveys keep surfacing, and it is why this site existed in the first place: it measured type-annotation coverage across popular PyPI packages to make the gap visible.
That measurement is now retired, and the job has passed to a tool that does it better. Joren's Typestats dashboard tracks package typing across the ecosystem today. Our historical data stays online, unchanged and clearly frozen. The two use different methodologies, so don't read them as one continuous trend.
There are now several mature Python type checkers, most with a language server attached. We run two benchmarks daily against a shared corpus of open-source Python projects.
Wall-clock execution time and peak memory when checking open-source Python projects from a cold start.
Measures: mypy · Pyright · Pyrefly · ty · Zuban
textDocument/definition (Go to Definition) latency,
how often a request completes without error, and whether the
location returned is valid.
Measures: Pyright · Pyrefly · ty · Zuban
Performance is one dimension of choosing a tool, and the easiest one to measure. These numbers say nothing about type-checking correctness, language-feature completeness, or which checker suits a given project. A returned definition location that exists is not automatically the semantically right one.
For the other dimension, the Typing Council publishes a conformance test suite and results, which report how each checker behaves against the typing specification. Read it alongside these benchmarks: a fast checker that disagrees with the spec is not obviously the right choice.
The library-typing gap closes one package at a time, and the work is unusually tractable: a small, well-scoped annotation fix to a widely used package helps everyone who imports it.
Start with a dependency whose gaps you've actually hit. Read its contribution policy first, then propose a small improvement to the public API surface, and add a test so it doesn't regress.
When a package can't ship its own types, typeshed carries them for the whole ecosystem. A fix there reaches every checker and every downstream user at once.
Annotation coverage tends to drift back down unless something in CI notices. A threshold check is a cheap ratchet. Pyrefly is one tool that reports coverage; other checkers offer comparable reporting.
# Example annotation-coverage gate. Pick a threshold that
# reflects where your project is today, then raise it.
pyrefly coverage check src/ --fail-under 80
Install or pin a Pyrefly version that supports this command, point
it at your real source path, and take a baseline before choosing a
number. Ordinary coverage counts an annotation even when it is
Any; --strict excludes those, and
--public-only narrows it to your exported surface.
Annotation coverage is not a quality score. It is not
test coverage, it is not type completeness in every sense, and it is
certainly not proof of correctness. What the annotations actually say,
how the checker is configured, and how much Any is hiding
inside them all matter more than the percentage. Never add
Any to move a number.
This is a question, not a finding. But it is worth asking, because coding agents are now another reader, and author, of Python.
Types encode things an agent otherwise has to guess: the shape of the data, where an API boundary is, what a function promises to return. Checker diagnostics are a fast, precise feedback signal on a proposed edit, available before anything runs. Both properties look useful for navigating a repository, refactoring across it, and validating a change.
How much that helps in practice depends on the task, the tooling, the configuration, and, again, the quality of the annotations involved. We don't have a number for it, and we would rather say so than invent one.
And passing a type checker has never meant a program is correct. It doesn't establish that the logic is right, and it doesn't remove the need for tests, runtime validation, review, or security analysis. That was true before agents and it stays true now.
Typing's open questions are not only about agents, either: easier adoption in existing codebases, clearer diagnostics and documentation, more consistent behaviour between checkers, and better ways to express what real library APIs actually do.
Python's type system got here through proposals, implementations, stub contributions and a lot of argument in public. That is still how it moves.
Python typing is still evolving. Help shape what comes next.