{"id":5015,"library":"pybind11-stubgen","title":"Pybind11 Type Stub Generator","description":"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.","status":"active","version":"2.5.5","language":"en","source_language":"en","source_url":"https://github.com/sizmailov/pybind11-stubgen","tags":["type stubs","pybind11","mypy","static analysis","ffi","c++","typing"],"install":[{"cmd":"pip install pybind11-stubgen","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python version 3.7 or higher.","package":"python","optional":false}],"imports":[{"note":"The primary entry point for programmatic use, mirroring the CLI behavior. Most users interact via the command-line interface.","symbol":"main","correct":"from pybind11_stubgen import main"}],"quickstart":{"code":"import os\nimport subprocess\nimport shutil\n\n# To generate stubs for a pybind11 module named 'my_module':\n# 1. Ensure 'my_module' is installed and importable in your Python environment.\n# 2. This example demonstrates generating stubs for the 'numpy' module.\n#    (Requires numpy to be installed: `pip install numpy`)\n\n# Create a temporary directory for output\noutput_dir = \"temp_stubs\"\nos.makedirs(output_dir, exist_ok=True)\n\ntry:\n    print(f\"Generating stubs for 'numpy' into '{output_dir}'...\")\n    # Execute the command-line tool\n    result = subprocess.run(\n        [\"pybind11-stubgen\", \"numpy\", \"-o\", output_dir],\n        capture_output=True,\n        text=True,\n        check=True\n    )\n    print(\"STDOUT:\", result.stdout)\n    print(\"STDERR:\", result.stderr)\n    print(f\"\\nStubs generated in '{output_dir}'. Contents:\")\n    for root, _, files in os.walk(output_dir):\n        for f in files:\n            print(os.path.join(root, f))\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error generating stubs: {e}\")\n    print(\"STDOUT:\", e.stdout)\n    print(\"STDERR:\", e.stderr)\nexcept FileNotFoundError:\n    print(\"Error: 'pybind11-stubgen' command not found. Is it installed and in your PATH?\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up the temporary directory\n    if os.path.exists(output_dir):\n        print(f\"\\nCleaning up '{output_dir}'...\")\n        shutil.rmtree(output_dir)","lang":"python","description":"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."},"warnings":[{"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`.","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to `pybind11-stubgen` version 2.5.5 or newer to ensure compatibility and correct stub generation for `pybind11 3.0.0` modules.","message":"Older 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.","severity":"breaking","affected_versions":"<2.5.5"},{"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.","message":"Handling 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.","severity":"gotcha","affected_versions":"<2.4"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}