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-stubgenVerified import paths — ran on the pinned version, not inferred.
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.
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`.
Upgrade to `pybind11-stubgen` version 2.5.5 or newer to ensure compatibility and correct stub generation for `pybind11 3.0.0` modules.
Upgrade to `pybind11-stubgen` v2.4 or newer, and consider using the `--numpy-array-use-type-var` flag for improved NumPy array type annotations.
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`.
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.
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).