{"id":23046,"library":"bpy","title":"Blender Python Module (bpy)","description":"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).","status":"active","version":"5.1.1","language":"python","source_language":"en","source_url":"https://github.com/TylerGubala/blenderpy","tags":["blender","3d","modeling","rendering","animation","scripting"],"install":[{"cmd":"pip install bpy","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"Avoid wildcard imports; bpy is a large module and can cause namespace pollution.","wrong":"from bpy import *","symbol":"bpy","correct":"import bpy"}],"quickstart":{"code":"import bpy\n\n# Clear the default scene\nbpy.ops.object.select_all(action='SELECT')\nbpy.ops.object.delete(use_global=False)\n\n# Add a monkey primitive\nbpy.ops.mesh.primitive_monkey_add()\n\n# Access the active object\nobj = bpy.context.object\nprint('Object:', obj.name)\n\n# Render an image (requires a camera and light, omitted for brevity)\n# bpy.ops.render.render(write_still=True)","lang":"python","description":"Minimal example: imports bpy, clears scene, adds Suzanne the monkey, and prints the object name."},"warnings":[{"fix":"Use Python 3.13 exactly. Check with `python --version`.","message":"bpy is only compatible with Python 3.13.x. Installing on other Python versions will fail or cause import errors.","severity":"gotcha","affected_versions":"5.x"},{"fix":"Always match the bpy version to your Blender version if using Blender's bundled Python. For standalone use, check release notes.","message":"The bpy pip package is not the same as the Blender-internal bpy. Breaking changes may occur between Blender releases.","severity":"breaking","affected_versions":"all"},{"fix":"Use a virtual display like Xvfb: `xvfb-run python script.py` or set `DISPLAY=:99`.","message":"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).","severity":"gotcha","affected_versions":"all"},{"fix":"Check Blender API docs for updated operators. Use `bpy.ops.mesh.primitive_monkey_add()` instead of legacy calls.","message":"Old API calls like `bpy.ops.object.add()` with deprecated parameters may cause errors in newer versions.","severity":"deprecated","affected_versions":">=5.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install Python 3.13 and create a virtual environment: `python3.13 -m venv venv && source venv/bin/activate && pip install bpy`","cause":"bpy 5.x only supports Python 3.13.","error":"RuntimeError: Error: Python version check: 3.x found, but 3.13 required"},{"fix":"Run `pip install bpy` to install the package.","cause":"bpy is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'bpy'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}