STUBGEN(1)

📦
version 2.2.0 · 11 versions
, in ubuntu stonking

✨ STUBGEN(1) ✨

okay bestie, gather round, because today we're talking about stubgen from the Mypy manual (section 1, if you're keeping track at home) 💖

🌸 NAME 🌸

stubgen — generate draft type hint stubs for Python modules 🐍✨

🦋 SYNOPSIS 🦋

stubgen [-h] [-py2] [-m MODULE] [-p PACKAGE] [OPTIONS...] [FILES...]

💅 DESCRIPTION 💅

So like. Mypy is a static type checker for Python 3 and Python 2.7 (we contain multitudes), and it comes with this little tool called stubgen that will just... automatically generate stub files (.pyi files) for Python modules and C extension modules. No cap. 🔥

A stub file (as per PEP 484, iykyk) contains only the type hints for the public interface of a module, with the function bodies left empty. Mypy can then use the stub file instead of the real implementation to get type info for that module. These are lowkey iconic for:

  • third-party modules whose authors haven't added type hints yet (and where no stubs exist in typeshed)
  • C extension modules (which mypy can't directly process)

Now, important: stubgen generates draft stubs. The auto-generated files usually need some manual love, and most types will just default to Any 💀. Your stubs are gonna be so much more useful if you go in and add more precise type annotations — at least for the stuff you actually use all the time. Do it for her (her = future you).

✨ OPTIONS ✨

heads up bestie: the command-line flags may change between releases. so don't get too attached okay 😭

🎀 Specifying what to stub

You can hand stubgen the paths of the source files you want stubs for:

$ stubgen foo.py bar.py

This generates stubs out/foo.pyi and out/bar.pyi. The default output directory out can be overridden with -o DIR (more on that below, scroll down bestie 👇).

You can also pass directories, and stubgen will recursively search them for any .py files and generate stubs for all of them:

$ stubgen my_pkg_dir

Alternatively (your other option, your alternate route, your plan B 💜), you can give module or package names using the -m or -p options:

$ stubgen -m foo -m bar -p my_pkg_dir

Details of the options, because you know I'm gonna give you the details:

  • -m MODULE, --module MODULE — Generate a stub file for the given module. This flag may be repeated multiple times.

Stubgen will not recursively generate stubs for any submodules of the provided module.

  • -p PACKAGE, --package PACKAGE — Generate stubs for the given package. This flag maybe repeated multiple times. (yes, it really says "maybe" in the original, we love a typo moment 🫶)

Stubgen will recursively generate stubs for all submodules of the provided package. This flag is identical to --module apart from this behavior.

Note: You can't mix paths and -m/-p options in the same stubgen invocation. Pick a lane, babe 🚫

Stubgen applies heuristics to avoid generating stubs for submodules that include tests or vendored third-party packages (she's self-aware, she knows what's noise).

🌈 Specifying how to generate stubs

By default, stubgen will try to import the target modules and packages. This lets stubgen use runtime introspection to generate stubs for C extension modules and to level up the quality of the generated stubs ✨. By default, stubgen will also use mypy to do light-weight semantic analysis of any Python modules. Use the following flags to alter the default behavior:

  • --no-import — Don't try to import modules. Instead only use mypy's normal search mechanism to find sources. This does not support C extension modules. This flag also disables runtime introspection functionality, which mypy uses to find the value of __all__. As a result, the set of exported imported names in stubs may be incomplete. This flag is generally only useful when importing a module causes unwanted side effects, such as the running of tests. Stubgen tries to skip test modules even without this option, but this does not always work (she's trying her best 😭).
  • --no-analysis — Don't perform semantic analysis of source files. This may generate worse stubs — in particular, some module, class, and function aliases may be represented as variables with the Any type. This is generally only useful if semantic analysis causes a critical mypy error. Does not apply to C extension modules. Incompatible with --inspect-mode.
  • --inspect-mode — Import and inspect modules instead of parsing source code. This is the default behavior for C modules and pyc-only packages. The flag is useful to force inspection for pure Python modules that make use of dynamically generated members that would otherwise be omitted when using the default behavior of code parsing. Implies --no-analysis as analysis requires source code.
  • --doc-dir PATH — Try to infer better signatures by parsing .rst documentation in PATH. This may result in better stubs, but currently it only works for C extension modules.

⭐ Additional flags

  • -h, --help — Show help message and exit. (the classic 🎀)
  • --ignore-errors — If an exception was raised during stub generation, continue to process any remaining modules instead of immediately failing with an error.
  • --include-private — Include definitions that are considered private in stubs (with names such as _foo with single leading underscore and no trailing underscores).
  • --export-less — Don't export all names imported from other modules within the same package. Instead, only export imported names that are not referenced in the module that contains the import.
  • --include-docstrings — Include docstrings in stubs. This will add docstrings to Python function and classes stubs and to C extension function stubs.
  • --search-path PATH — Specify module search directories, separated by colons (only used if --no-import is given).
  • -o PATH, --output PATH — Change the output directory. By default the stubs are written in the ./out directory. The output directory will be created if it doesn't exist. Existing stubs in the output directory will be overwritten without warning. 💀 back up your stuff, bestie, she is NOT asking permission.
  • -v, --verbose — Produce more verbose output. (she's yapping, lovingly 💜)
  • -q, --quiet — Produce less verbose output. (she's giving nothing, on purpose 🎀)

🧚 ENVIRONMENT 🧚

  • MYPYPATH — Additional module search path entries. The format is the same as the shell's $PATH: one or more directory pathnames separated by colons.

👑 SEE ALSO 👑

Full documentation is available online at: <https://mypy.readthedocs.io/en/latest/stubgen.html> or locally at: /usr/share/doc/mypy/html <file:///usr/share/doc/mypy/html> (requires mypy-doc package).

🫶 Author

Jukka Lehtosalo and contributors 🌸

and that's the whole page, bestie — this one came from the Mypy source, version dated Aug 16, 2026, and it's officially a wrap. go forth and generate some stubs, you absolute icon 💅✨periodt

📦 where this page comes from