Building Blender/Other/BlenderAsPyModule

Overview

The official blender.org embeds a Python interpreter (CPython 3.x). This makes sense from the perspective of a user, who's primary needs are to have an application which can be extended with scripts.

However from the perspective of a Python developer, it can be useful to being Blender into your existing scripts and access its feature set.

The option to build Blender as a Python module is not officially supported, in the sense Blender.org isn't distributing it along with regular releases, Currently, its a build option you can enable, for your own use.

Rationale

This is a build option to be able to import blender into python and access its modules

Possible uses include:

  • rendering animations.
  • image processing using Blender's compositor.
  • video editing (using Blender's sequencer).
  • importers, exporters (convert 3D file formats).
  • development, accessing bpy from Python IDE's and debugging tools for example.
  • automation.

This is mainly limited to features which can be usable in background mode, so you cant for instance do OpenGL preview renders.

Prerequisites

OSX

get Python3.x-framework from Python.org and install it.

Building

Assuming you have a CMake out-of-source build setup, see building blender docs.

Change these CMake options from the defaults:

WITH_PYTHON_INSTALL=OFF
WITH_AUDASPACE=OFF
WITH_PYTHON_MODULE=ON

Everything should build as normal except in the cmake directory you will have ./bin/bpy.so instead of ./bin/blender

See: build_files/cmake/config/bpy_module.cmake for supported default values, although you may want to adjust these depending on your usage.

Installation

Linux

System Wide Install

You may want to copy into the module to the systems Python path, eg:

/usr/lib/python3.7/site-packages

For a system wide installation:

WITH_INSTALL_PORTABLE=OFF

note, PYTHON_SITE_PACKAGES will be used as the target path, but this is auto detected, nevertheless, you may want to modify.

Once these optiosn are set, run:

 make install

Local Install

Alternately you might want to use your user Python path (see https://www.python.org/dev/peps/pep-0370/)

$HOME/.local/lib/python3.7/site-packages

For a local install use the following options:

WITH_INSTALL_PORTABLE=ON
CMAKE_INSTALL_PREFIX=$HOME/.local/lib/python3.7/site-packages

Once these optiosn are set, run:

 make install

Windows

copy bin\bpy.pyd C:\Python37\Lib\site-packages\
copy bin\*.dll C:\Python37\Lib\site-packages\
del C:\Python37\Lib\site-packages\python37.dll
xcopy /E bin\2.81 C:\Python37\

OSX

After compiling and "make install", copy needed files to your python framework

cp ./bin/bpy.so /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/
cp -R ./bin/2.81 /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/

Note. Unlike on *nix C:\Python37\2.81 is not in the site packages, this is because of a difference in how Windows finds the scripts path and should eventually be fixed.

Testing

This allows 'bpy' to be imported from python or other applications/IDE's which embed python, eg:

python -c "import bpy; bpy.ops.render.render(write_still=True)"

Or:

python -c "import bpy; bpy.ops.wm.save_as_mainfile(filepath='my.blend')" 

This runs in background mode and has similar restrictions to running a script:

blender --background --python test.py

Troubleshooting

  • The Python version requirements are the same with building a regular blender binary (if Blender us using Python3.7 then there is NO WAY to use another version - 2.7..3.5/3.6 will all fail).
  • On Windows, you probably won't want to use a debug build, since this requires a debug python installation (python37_d.dll rather then python37.dll), so while it can be made to work, its more trouble.