pybind11-stubgen

What it is and what it does

pybind11-stubgen is a command-line tool that introspects compiled Python extensions and generates PEP 561 type stub files (.pyi) for them. Binary extensions—whether built with pybind11, ctypes, or other C/C++ binding libraries—are normally opaque to static type checkers and IDEs because their signatures and types exist only at runtime in compiled code. This tool bridges that gap by extracting type information from the running module and writing it out as stub files that tools like mypy, pyright, and IDEs can read.

The tool is designed primarily for pybind11 modules but works with other binding approaches. It offers command-line options to handle edge cases like invalid expressions, unresolved names, and special handling for NumPy arrays. Once stubs are generated, they sit alongside your extension modules and enable full IDE autocomplete, type checking, and documentation generation for code that uses those extensions.

Use it for:

• Generate stubs for NumPy or other scientific C extensions so type checkers can validate code using them.
• Enable IDE autocomplete and inline documentation for third-party binary modules without source access.
• Create type stubs for in-house pybind11 modules to integrate them into a typed Python codebase.
• Support static analysis in CI/CD pipelines that use mypy or similar tools on code importing compiled extensions.
• Publish type information alongside a compiled extension package to improve downstream user experience.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates PEP 561 type stubs for Python binary extensions, making them visible to static analysis tools and IDEs by introspecting compiled modules.

Yes, if you work with Python binary extensions and want static type checking or IDE support for them. It has no runtime dependencies, low friction, and solves a real problem—making opaque compiled code visible to the Python tooling ecosystem. Install it as a development or build-time tool.

Install

pybind11-stubgen on PyPI

pip install pybind11-stubgen

uv add pybind11-stubgen

poetry add pybind11-stubgen

Installing pybind11-stubgen

Before you install

Low install friction; no runtime dependencies. Actively maintained with recent commits and a steady release cadence since 2019.

License in practice

BSD license is permissive; you may use, modify, and distribute this package with minimal restrictions.

Quickstart

pip install pybind11-stubgen
pybind11-stubgen numpy

Requires Python ~=3.7 or later; the target module must be importable in the environment where stubs are generated.

Verify before relying

• How well stub generation works for non-pybind11 extensions (documentation mentions it 'should work well' but provides no compatibility matrix).
• Whether generated stubs are compatible with all major type checkers (mypy, pyright, etc.) or have known limitations.

Package facts

Evidence: pybind11_stubgen-2.5.5-py3-none-any.whl

Tags

More Build Tools packages