What is typeshed, and where does a type checker get stdlib and third-party stubs?

### What typeshed actually is typeshed is a single open-source repository of **type stubs**: `.pyi` files that carry declarations only, with `...` standing in for every function body. It has two halves that behave quite differently. `stdlib/` holds stubs for the standard library — every module, including the ones implemented in C. `stubs/` holds stubs for third-party projects that ship no annotations of their own; each lives in its own directory with a small metadata file, and each is published to the package index as a **separate stub-only distribution**, conventionally named `types-<project>`. ### Why the standard library is stubbed at all You might expect a checker to read type information out of the installed standard library. It does not. Large parts of CPython's Python-level source are unannotated, and modules implemented in C have no Python source to annotate in the first place. So a checker ships a vendored copy of typeshed's `stdlib/` stubs inside the tool and reads those instead. That has a useful consequence: the checker's model of the standard library is decoupled from the interpreter you happen to be running. Version differences are expressed *inside* the stub with `sys.version_info` branches, and the checker keeps the branch matching the Python version you ask it to target. You can run the tool under 3.14 while checking that your code stays valid on 3.10 — the stub, not the running interpreter, decides which names and signatures exist. ### The three ways a third-party package can be typed 1. **Inline** — the project annotates its own source and ships an empty `py.typed` marker inside the importable package, so a checker knows those annotations are meant to be consumed by callers. 2. **A stub-only distribution** — a separate installable distribution containing only `.pyi` files, in a directory named `<package>-stubs`. Nothing in it is ever imported at runtime; the `-stubs` suffix is the convention a checker looks for. 3. **typeshed's third-party stubs** — the `types-<project>` distributions described above, maintained by people who are usually not the library's authors. Note the vocabulary trap, and it is the one that costs people an afternoon: the installed *distribution* and the importable *package* deliberately have different names here. Installing a distribution called `types-acmeutil` drops a directory called `acmeutil-stubs` into site-packages, while the code you write still imports `acmeutil`. ### The precedence order PEP 561 fixes the order a checker searches, and it matters more than most people expect: 1. Stubs on the checker's own configured search path — a directory of hand-written stubs you point the tool at. (How you configure that path is the individual checker's business, not the language's.) 2. An installed `<package>-stubs` distribution. 3. The installed package's own inline annotations, if it contains a `py.typed` marker. 4. typeshed's bundled third-party stubs for that project. The load-bearing line is 2 before 3: **a stubs package beats the library's own inline annotations.** That is deliberate — it lets you override a wrong or incomplete upstream annotation without patching the dependency — but it also produces one of the most confusing failures in typed Python. A library adds annotations and a `py.typed` marker, typeshed removes and marks its stubs obsolete, but an old `types-*` pin is still in your lockfile; the stale stubs keep winning, and the checker reports errors against a signature the library abandoned two releases ago. The fix is to uninstall the stubs distribution, not to sprinkle ignores. ### Practical consequences Stubs version independently of the code they describe, so "the checker insists this attribute does not exist, but it plainly does at runtime" is nearly always a stub-freshness problem: the installed stub distribution is older than the installed library. Treat the stub pin as part of that dependency and bump the two together. Because a stub replaces the module's public interface *entirely* for the checker, anything missing from the stub is missing as far as the checker is concerned, even though it exists at runtime. A partial stub is a perfectly legitimate choice — it types the surface you actually use — but the gaps surface as `Any` and silence, not as errors, which is exactly the failure mode gradual typing is supposed to make visible. Everything here is a **static** artefact. No `.pyi` file is ever imported, `py.typed` is empty and exists only to be found, and a stub-only distribution installs no runtime code whatsoever. Python 3.14's deferred annotations (PEP 649) changed how annotations in real source are evaluated at runtime; they changed nothing about stubs, whose annotations were never evaluated in the first place. Finally, the two halves of typeshed have very different reliability profiles. The standard-library stubs are effectively canonical and evolve with each release. The third-party stubs are best-effort community work, and they are retired from typeshed once a project starts shipping its own types — which is the outcome you should want for any library you maintain.