Registry / type-stubs / pybind11-stubgen

pybind11-stubgen

JSON →
library2.5.5pypypi✓ verified 24d ago

pybind11-stubgen is a PEP 561 type stubs generator for pybind11 modules. It creates `.pyi` files, making C++ extensions more understandable to static analysis tools and IDEs for improved type checking. The project is actively maintained, with regular releases (currently at version 2.5.5) providing bug fixes and new features.

pip install pybind11-stubgen
INSTALL
IMPORT
SIG · PYBIND11-STUBGEN
P
pybind11-stubgen
type-stubspythonv2.5.5
Install
1.6s avg
Import
105ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.5.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.114s · 18.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.096s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

main
from pybind11_stubgen import main
The primary entry point for programmatic use, mirroring the CLI behavior. Most users interact via the command-line interface.

This quickstart demonstrates how to use `pybind11-stubgen` via its command-line interface to generate type stubs for an existing module (e.g., `numpy`). Ensure the target module is importable in your environment before running the stub generator.

import os import subprocess import shutil # To generate stubs for a pybind11 module named 'my_module': # 1. Ensure 'my_module' is installed and importable in your Python environment. # 2. This example demonstrates generating stubs for the 'numpy' module. # (Requires numpy to be installed: `pip install numpy`) # Create a temporary directory for output output_dir = "temp_stubs" os.makedirs(output_dir, exist_ok=True) try: print(f"Generating stubs for 'numpy' into '{output_dir}'...") # Execute the command-line tool result = subprocess.run( ["pybind11-stubgen", "numpy", "-o", output_dir], capture_output=True, text=True, check=True ) print("STDOUT:", result.stdout) print("STDERR:", result.stderr) print(f"\nStubs generated in '{output_dir}'. Contents:") for root, _, files in os.walk(output_dir): for f in files: print(os.path.join(root, f)) except subprocess.CalledProcessError as e: print(f"Error generating stubs: {e}") print("STDOUT:", e.stdout) print("STDERR:", e.stderr) except FileNotFoundError: print("Error: 'pybind11-stubgen' command not found. Is it installed and in your PATH?") except Exception as e: print(f"An unexpected error occurred: {e}") finally: # Clean up the temporary directory if os.path.exists(output_dir): print(f"\nCleaning up '{output_dir}'...") shutil.rmtree(output_dir)
pybind11-stubgen --version
Debug
Known issues
gotchaThe target pybind11 module (for which stubs are being generated) must be discoverable and importable by Python at runtime. If the module is not formally installed (e.g., a development build), you may need to adjust `PYTHONPATH` or `LD_LIBRARY_PATH` (on Linux) to ensure it can be found.
fix
Ensure the module is installed via `pip install .` or set appropriate environment variables (e.g., `export PYTHONPATH=/path/to/module:$PYTHONPATH`) before running `pybind11-stubgen`.
affects: All
breakingOlder versions of `pybind11-stubgen` (prior to 2.5.5) may generate incorrect or malformed stubs for modules built with `pybind11 3.0.0` due to changes in how `qualname` prefixes are handled within `pybind11` itself.
fix
Upgrade to `pybind11-stubgen` version 2.5.5 or newer to ensure compatibility and correct stub generation for `pybind11 3.0.0` modules.
affects: <2.5.5
gotchaHandling of NumPy array type annotations can be inconsistent in older versions. Before v2.4, or without explicitly using the `--numpy-array-use-type-var` flag, NumPy array types like `numpy.ndarray[numpy.float32[m, 1]]` might not be formatted optimally for static analysis.
fix
Upgrade to `pybind11-stubgen` v2.4 or newer, and consider using the `--numpy-array-use-type-var` flag for improved NumPy array type annotations.
affects: <2.4
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'your_pybind_module'
The Python C++ extension module for which stubs are being generated is not discoverable by the Python interpreter or pybind11-stubgen.
fix
Ensure the directory containing the compiled '.so' (or '.pyd') file of your pybind11 module is added to the PYTHONPATH environment variable before running pybind11-stubgen. For example: `export PYTHONPATH=/path/to/your/module:$PYTHONPATH` on Linux/macOS or `set PYTHONPATH=/path/to/your/module;%PYTHONPATH%` on Windows, then run `pybind11-stubgen your_pybind_module`.
Unexpected "..." [misc] (or similar Mypy errors regarding Ellipsis)
Type checkers like Mypy do not always correctly interpret the Ellipsis (`...`) that pybind11-stubgen uses in generated stubs for unknown or incomplete types, leading to syntax errors or type checking warnings.
fix
Use pybind11-stubgen's options to control type representation, such as `--ignore-invalid-expressions REGEX` to filter problematic patterns. Alternatively, consider post-processing the generated `.pyi` file to replace `...` with `Any` or `_typeshed.Incomplete` where appropriate, or consult the pybind11-stubgen documentation for flags that modify default type emission for unsupported types.
ModuleNotFoundError: No module named 'your_module.pybind11_detail_...' (in generated .pyi file)
The generated `.pyi` file includes overly specific import paths, often containing ABI-specific suffixes (e.g., `pybind11_detail_function_record_v1_system_libstdcpp_gxx_abi_1xxx_use_cxx11_abi_1`) that do not correspond to actual importable Python modules.
fix
This issue is often a bug in specific versions of `pybind11-stubgen` (e.g., reported in version 3.0.0 for certain cases). Check if updating to the latest `pybind11-stubgen` version resolves it. If not, you may need to manually edit the generated `.pyi` files to simplify the import paths to the correct, more general module name (e.g., `from your_module import ...` instead of the ABI-suffixed version).
Upgrade
Version history
2.5.5latest on PyPI · released Aug 9, 2025
Audit
Dependencies
pythonrequiredRequires Python version 3.7 or higher.
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
pybind11-stubgen — pip install pybind11-stubgen · libregistry