fake-bpy-module for Blender Python Code Completion

Why fake-bpy-module exists for Blender script editors

Code completion for a Blender add-on can be difficult when the script is edited in an IDE without suitable API definitions. `fake-bpy-module` addresses that narrow problem. It provides fake Blender Python API modules intended for code completion in commonly used IDEs.

The intended users are Python developers writing Blender add-ons and scripts who want names, signatures, and type hints to be visible while editing. The package does not replace Blender, render a scene, create `bpy` data at runtime, or turn a normal Python process into a Blender instance. Its value is editor assistance, so treating it as the real runtime module would lead to the wrong conclusion.

Version selection matters because the package set follows Blender releases. The README lists packages from Blender 2.78 through 5.2, plus packages for the latest build and its main branch. That range is broader than a single universal package. A developer working against Blender 4.2 should prefer the package published for 4.2 rather than assuming the latest package represents the same API surface.

How the generated bpy package reaches Python tooling

The repository describes the project as a collection of fake Blender Python API modules. Its packaging configuration includes `.pyi` files and `py.typed` markers in package data, which indicates that Python tooling receives stub-style API information rather than an implementation of Blender's rendering and data systems. The package metadata classifies it as a Python tool for IDEs, 3D modeling, and 3D rendering.

The intended data flow is straightforward. A Python IDE reads the installed package, discovers the `bpy` namespace and its generated definitions, and uses those definitions while parsing or completing code. Type hints and the typing module are central to that process. The project requires Python 3.8 or newer because those capabilities are available from that version.

The presence of `src/`, `tools/`, tests, and separate generation documentation also indicates that the distributed files are produced from Blender API information rather than assembled only as handwritten convenience wrappers. The generator's extraction algorithm is not described. What can be confirmed is the output format: fake API modules, package data containing `.pyi` files, and support for IDE completion. The repository also provides manual generation instructions in `docs/generate_modules.md`, but the README excerpt does not include their commands.

Installing fake-bpy-module and configuring PyCharm

The simplest setup is the latest package. Use this when the script targets the latest Blender build described by the README, specifically the main branch daily build.

pip install fake-bpy-module

The README also provides a separate package name for an explicitly named `latest` target.

pip install fake-bpy-module-latest

For a stable Blender release, install the package whose version matches the project. For example, a script targeting Blender 2.93 uses the following command.

pip install fake-bpy-module-2.93

After installation, restart or reload the Python environment if the IDE does not immediately recognize the new package. Then open a Python file that imports `bpy` and request completion from the editor. The expected result is editor suggestions based on the installed fake package, not the ability to run Blender operations outside Blender.

PyCharm has an additional constraint. The README says some modules are large enough to exceed IntelliSense processing limits. Change `idea.max.intellisense.filesize` in `idea.properties` to a value greater than `2600`. The excerpt does not document the exact property-file format or a supported IDE version, so the value should be applied according to the IDE's existing properties syntax.

Pre-generated modules for Visual Studio Code and other editors

A package installation is convenient, but it is not the only documented path. The project publishes pre-generated modules through its GitHub Release page. The README directs users to separate setup documents for PyCharm, Visual Studio Code, and installation as a Python module for other text editors.

This distinction matters because IDE completion often depends on how the editor discovers Python packages. Visual Studio Code may use a selected interpreter or a configured path, while an editor without package introspection may need the generated modules installed into a directory that its language server searches.

The pre-generated route is most relevant when a developer wants to avoid generating the modules locally, or when an IDE needs files arranged differently from the PyPI package. The manual generation route is documented separately and should be treated as an alternative for contributors or users who need to reproduce the package from repository inputs. The public documentation does not establish that manually generated output is byte-for-byte identical to a release, so that should not be assumed.

Version coverage, dependencies, and upgrade work

The supported package table gives users a direct choice based on Blender version. It includes releases from `fake-bpy-module-2.78` through `fake-bpy-module-5.2`, as well as `fake-bpy-module` and `fake-bpy-module-latest`. This reduces the need to guess whether a new package corresponds to a stable Blender release, although the project still requires the user to keep that mapping current.

The Python requirement is explicit: version 3.8 or later. The packaging file also declares runtime dependencies on `typing_extensions>=4.7,<5` and `numpy>=1.21`. Those constraints matter in environments where Blender's Python runtime, an IDE interpreter, and a development environment differ. Installing a completion package into the wrong interpreter can leave the editor without `bpy` suggestions even when the command appears to succeed in another environment.

The repository is not archived. Its last push was on 2026-08-09, and releases include `20260730`, `20260128`, and `20250130`. Those dates indicate recent project activity, but they do not guarantee that every Blender API is represented accurately in every package. Upgrade cost is therefore tied to Blender version changes and to the editor's indexing behavior. The MIT license permits use and modification under its terms, while redistribution and dependency compliance remain separate project-specific checks.

What fake-bpy-module cannot do

The largest limitation is semantic rather than cosmetic: these modules are fake. A completion result can show that a name exists in the generated API set, but it cannot prove that the corresponding code works in a particular Blender build, operator context, addon configuration, or platform. Static definitions also cannot model every runtime condition that affects Blender data access.

Large modules can also overwhelm editor tooling. The README calls out PyCharm's `idea.max.intellisense.filesize` setting specifically, which is evidence that completion support has a practical indexing boundary. Raising the limit may expose the definitions, but the README does not claim that this removes every indexing or performance issue.

The wrong choice is using `fake-bpy-module` as a substitute for an actual Blender runtime. It is also a poor fit for a project that only needs generic Python tooling without `bpy` completion. For code that must execute `bpy` operations, the real Blender environment remains the authority. For a different engine, the README points to `fake-bge-module`, which targets UPBGE and is a distinct API surface.

Choosing between fake-bpy-module and a real Blender environment

The practical alternative is to develop and test the script with Blender's actual bundled Python environment. That approach can execute operators and inspect real scene data, but it does not automatically provide the same completion experience in an external IDE. `fake-bpy-module` takes the opposite approach: it prioritizes editor-facing declarations and leaves runtime execution to Blender.

For Blender add-on development, these approaches can be complementary. Use a version-matched fake package while editing, then run the code in Blender for behavioral checks. Choose the real environment first when debugging data mutations, operators, context-sensitive behavior, or anything that depends on Blender's actual state. Choose the fake package first when the immediate problem is missing names, signatures, or type information in an IDE.

For UPBGE projects, `fake-bpy-module` is not the documented choice. The README identifies `fake-bge-module` as the similar project targeting UPBGE. That distinction is important because a similarly named completion package can still expose the wrong API namespace.

Editorial conclusion

Developers editing Blender add-ons or scripts outside Blender should adopt a version-specific `fake-bpy-module` package when their IDE lacks useful `bpy` completion. Developers who need executable Blender behavior should use Blender itself instead. Check the target Blender version, Python requirement, and PyCharm IntelliSense file-size setting first.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nutti/fake-bpy-module on GitHub
4. README
5. Releases