Blender Python Module (bpy)

5.1.1 verified Fri May 01 auth: no python

The official Blender Python module (bpy) allows you to run Blender's 3D modeling, animation, rendering, and scripting capabilities directly from Python, bypassing the GUI. Version 5.1.1 is the latest release, supporting Python 3.13 only. Updates are tied to Blender releases (roughly every 3-4 months).

pip install bpy

Common errors

error RuntimeError: Error: Python version check: 3.x found, but 3.13 required ↓

cause bpy 5.x only supports Python 3.13.

fix

Install Python 3.13 and create a virtual environment: python3.13 -m venv venv && source venv/bin/activate && pip install bpy

error ModuleNotFoundError: No module named 'bpy' ↓

cause bpy is not installed in the current Python environment.

fix

Run pip install bpy to install the package.

Warnings

gotcha bpy is only compatible with Python 3.13.x. Installing on other Python versions will fail or cause import errors. ↓

fix Use Python 3.13 exactly. Check with `python --version`.

breaking The bpy pip package is not the same as the Blender-internal bpy. Breaking changes may occur between Blender releases. ↓

fix Always match the bpy version to your Blender version if using Blender's bundled Python. For standalone use, check release notes.

gotcha bpy cannot run headlessly on all platforms without a display server. On Linux, you may need `DISPLAY=:0` or use `bpy.app.background = True` (but this may not work without a virtual display). ↓

fix Use a virtual display like Xvfb: `xvfb-run python script.py` or set `DISPLAY=:99`.

deprecated Old API calls like `bpy.ops.object.add()` with deprecated parameters may cause errors in newer versions. ↓

fix Check Blender API docs for updated operators. Use `bpy.ops.mesh.primitive_monkey_add()` instead of legacy calls.

Imports

bpy
wrong
```
from bpy import *
```
correct
```
import bpy
```
Avoid wildcard imports; bpy is a large module and can cause namespace pollution.

Quickstart

Minimal example: imports bpy, clears scene, adds Suzanne the monkey, and prints the object name.

import bpy

# Clear the default scene
bpy.ops.object.select_all(action='SELECT')
bpy.ops.object.delete(use_global=False)

# Add a monkey primitive
bpy.ops.mesh.primitive_monkey_add()

# Access the active object
obj = bpy.context.object
print('Object:', obj.name)

# Render an image (requires a camera and light, omitted for brevity)
# bpy.ops.render.render(write_still=True)