What does the py.typed marker file in a Python package do?

### The problem the marker solves Annotations are ordinary Python syntax: any library can write `def total(cents: int) -> int` without promising anything about them. When third-party type checking became practical, the ecosystem needed a way to distinguish a library that has *deliberately* annotated its public surface and stands behind those annotations from one that has a handful of decorative hints, or annotations used for something else entirely (a serialization framework, a dependency injector, a documentation tool). PEP 561 settled that with an explicit opt-in: a distribution declares "my inline annotations are for type checkers" by shipping a file named `py.typed` inside the importable package. ### Where it goes Inside the package directory, next to `__init__.py`: ``` billing/ __init__.py invoices.py py.typed ``` Not at the repository root, not next to `pyproject.toml`, and not in the `.dist-info` metadata directory the installer creates. The checker looks for it where the package is *installed* — in the environment's `site-packages` — so it has to be part of the built artefact, not merely present in your source tree. That distinction is where most of the real-world failures come from: the file exists in the repo, the wheel does not contain it, and every consumer sees an untyped dependency. The file is conventionally empty. For an inline-typed package its mere presence is the whole message. (The one case where contents matter is a stub-only package, where a `py.typed` holding the word `partial` marks the stubs as incomplete.) A single marker covers the package and everything under it, so `billing/invoices.py` and `billing/tax/rates.py` are both covered by `billing/py.typed`. If one distribution installs two independent top-level packages, each needs its own marker. ### What happens without it A checker that resolves `import billing` and finds no stub package, no marker and no bundled typeshed entry has to decide what `billing` is. It treats the module as untyped: the import is reported as having no type information, and every name reached through it degrades to `Any`. `Any` is contagious — it silences errors rather than producing them — so the practical damage is not a wall of red, it is a quiet hole in coverage. Code that calls your library gets no checking at all, and a genuine mistake such as passing a `str` where the library wants an `int` sails through. Consumers can suppress the report on their side, but suppressing it does not give them types; it only hides the fact that they have none. ### What it does not do Nothing at runtime reads `py.typed`. It does not enable runtime validation, it does not make the interpreter enforce annotations, and it does not change how or when annotations are evaluated. It is a static-analysis signal that happens to be delivered through the packaging system, which is why it is a packaging concern rather than a typing-syntax one: the decision is *shipped*, and it can be lost by the build. It is also a promise, not a proof. Adding the marker asserts that the annotations are intended to be consumed; if half your public functions are unannotated, a checker will infer `Any` for them and callers will silently get less checking than they think. The marker is therefore usually added at the point where a library starts checking itself as part of its own build, so that the promise stays true release over release. ### How a checker reaches the decision Resolution runs in a fixed order. A checker asked to resolve `import billing` looks first at stubs you have configured or vendored yourself, then for an installed `billing-stubs` package, then for `billing/py.typed` and the inline annotations it unlocks, and finally at the bundled stubs it ships for the standard library and for a curated set of third-party projects. The marker is one rung on that ladder, which explains two things people find surprising: a stub package can override your inline types even when you have shipped the marker, and a dependency can be fully typed for a consumer without shipping anything itself, if the checker already bundles stubs for it. ### The other direction A package you do not control cannot be marked by you. That is what a stub-only distribution is for: a separate distribution shipping `.pyi` files under a `<name>-stubs` directory, which a checker prefers over inline types. For your own library, though, the marker plus honest inline annotations is the cheaper and more durable answer, because the types live next to the implementation and cannot drift from it.