How to build Blender as a Python module?

Question

I have seen this question now many times and every question here and on other forum points to build blender as python module experimental tutorial by ideaman42. Now sadly a lot of answers are invalid right now because this central link is down. I couldn't find anything by Googling so if anybody has a fork of the tutorial or a second source that would be great? The link can't be gone for too long, I saw an answer with it 4 months ago.

The only other thing I have found is this tutorial for windows, but it also references the now missing tutorial. Any ideas how to find it?

Answer 1

Here it is pulled from the archive.is (all Ideasman42 cited):

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.6-Framework from Python.org and install it.

Building

---

Assuming you have a CMake out-of-source build setup, see: http://wiki.blender.org/index.php/Dev:Doc/Building_Blender/Linux/Ubuntu/CMake

Change these CMake options from the defaults:

WITH_PYTHON_INSTALL=OFF
WITH_PLAYER=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

Installation

---

Linux

• System Wide Install

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

  /usr/lib/python3.6/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.6/site-packages
  

  For a local install use the following options:

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

  Once these optiosn are set, run:

  make install
  

Windows

copy bin\bpy.pyd C:\Python36\Lib\site-packages\
copy bin\*.dll C:\Python36\Lib\site-packages\
del C:\Python36\Lib\site-packages\python36.dll
xcopy /E bin\2.79 C:\Python36\

OSX

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

cp ./bin/bpy.so 
/Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/
cp -R ./bin/2.79 
/Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/

Note. Unlike on *nix C:\Python36\2.79 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)"

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.6 then there is NO WAY to use another version - 2.7/3.2/3.6 will all fail).

On Windows, you probably won't want to use a debug build, since this requires a debug python installation (python36_d.dll rather then python36.dll), so while it can be made to work, its more trouble.

Answer 2

I struggeld probably the same way as you did but i managed to actually build it as a Python module in the End.

I'm on a Ubuntu 18.04 LTS System so the following report on how i achieved it might depend on the system.

Now to the process of the solution.

Starting point were the following three sources as follows :

1. Your Question here

2. An Archived Blender Wiki entry

3. The offical "Build from source" Wiki article

How did i achieve the build ?

I started by following the description provided of the 2. Source; which wasn't really precise in how to handle the source and so on and did not work for me in the end.

After a few failures of this, i went on by just following the 3. Source.

So i did what was stated there :

mkdir ~/blender-git
cd ~/blender-git
git clone https://git.blender.org/blender.git
cd blender
git submodule update --init --recursive
git submodule foreach git checkout master
git submodule foreach git pull --rebase origin master

Afterwards :

cd ~/blender-git
./blender/build_files/build_environment/install_deps.sh

Now I had every bit of blender code and all dependencies installed. Since i did not want blender compiled with UI (as normal programm) i was curious what (described in the next step, step 3, in Source 3.) make in ~/blender-git/blender offered. So i proceeded with simply calling make help which gave the following (truncated for brevity) output :

Convenience targets provided for building blender, (multiple at once can be used)
* debug     - build a debug binary
* full      - enable all supported dependencies & options
* lite      - disable non essential features for a smaller binary and faster build
* headless  - build without an interface (renderfarm or server automation)
* cycles    - build Cycles standalone only, without Blender
* bpy       - build as a python module which can be loaded from python directly
* deps      - build library dependencies (intended only for platform maintainers)

* config    - run cmake configuration tool to set build options

Note, passing the argument 'BUILD_DIR=path' when calling make will override the
default build dir.
Note, passing the argument 'BUILD_CMAKE_ARGS=args' lets you add cmake arguments.

"Oh Hey, look what we got!" There it was, a make bpy which promised to solve all my problems.

So i executed it and it compiled. But I ended up with the Python module in a, at least for my desires, wrong directory : /usr/local/PYTHON_SITE_PACKAGES-NOTFOUND. I wondered how this happend.

I soon figured out that I had to reconfigure cmake in the new created ~/blender-git/linux_build_bpy via ccmake linux_build_bpy while in ~/blender-git. There i needed to enable the Advanced Settings via pressing t and then editing the Key PYTHON_SITE_PACKAGES from PYTHON_SITE_PACKAGES-NOTFOUND to my desired Path /usr/lib/python3.6/site-packages.

After changing this i had to rebuild the project, which didn't actually rebuild since the changed setting didn't affect the main build process.

Rebuild in ~/blender-git/blender via make bpy.

In the End I also deleted the stuff in /usr/local/PYTHON_SITE_PACKAGES-NOTFOUND. (Ofc i could've just moved/copied it...)

That's how it worked form me. I hope this is helpful in any kind for anyone in the future.

NOTES:

1. make bpy might need superuser-rights so do a sudo make bpy and don't worry about a complete rebuild (it's allready done just linking/copying in the end needs those rights).

2. The configuration after the first build might not be needed or can be done before hand, but i didn't figure out how to do so.

3. If followed through these steps, and the Python module (strangely a directory called 2.80 or simmilar number) exists in the desired path but yet you are not able to import the module bpy in any of your scripts, make sure that your desired path is included in your PYTHONPATH Env-variable.

Answer 3

As of 2.80 release there is a convenience make target. As following this instruction, run make bpy in place of make full to automatically setup build parameters and compile Blender as a Python module.

Answer 4

Since building libraries can be a bit cumbersome at times, I started by looking for pre-built options.

Option 1 - PyR3

I found precompiled libraries from PyR3 for Blender 2.93.5 and Python 3.9 for Linux (and then I installed it on Ubuntu 20.04).

mkdir -p /home/ubuntu/_tmp/blender-precompiled
cd /home/ubuntu/_tmp/blender-precompiled 
wget -qO- https://github.com/Argmaster/pyr3/releases/download/bpy-binaries/bpy-2.93-linux64-py-3.9.tar.gz | tar xvz
sudo cp -r /home/ubuntu/_tmp/blender-precompiled/. /opt/conda/lib/python3.9/site-packages/
sudo apt-get install pulseaudio

To test the installation

python -c "import bpy; bpy.ops.render.render(write_still=True)" # will only work with a display
python -c "import bpy; bpy.context.scene.render.engine='CYCLES'; bpy.ops.render.render(write_still=True)"
python -c "import bpy; bpy.context.scene.render.engine='CYCLES'; bpy.context.scene.cycles.device='GPU'; bpy.ops.render.render(write_still=True)"

Note: they also have instructions and install files for Windows. Post may be useful for those who have a compatible system.

Option 2 - kitsune.one

I also tried installing via the conda channel of kitsune.one.

conda create --name blender3.2python3.10.5 python=3.10.5
conda activate blender3.2python3.10.5
conda install -c kitsune.one python-blender==3.2

Unfortunately they need Python 3.10 and also don't have cycles so you can't run the command

bpy.context.scene.render.engine='CYCLES'

They only have ('BLENDER_EEVEE', 'BLENDER_WORKBENCH') which many folks online were not able work with while using bpy.

Answer 5

If you have anaconda, it is quite simple to build a blender-python package, which will allow you to import bpy in a Python script. The following (slightly modified) instructions were obtained from (https://launchpad.net/blender-conda).

If you want to build from source, execute the following commands:

git clone https://git.launchpad.net/blender-conda
cd blender-conda
conda-build .
conda install python-blender --use-local

If you want to download prebuilt packages, use

conda install -c kitsune.one python-blender

Note that I have no relation to kitsune.one and cannot verify the integrity of the prebuilt packages.

Answer 6

There's no need to build full Blender to figure out it's target Python version. There's plenty places in Blender sources that point out to the supported Python version. For example, in CMakeLists.txt:

  if(DEFINED PYTHON_VERSION AND "${PYTHON_VERSION}" VERSION_LESS "3.7")
    message(FATAL_ERROR "At least Python 3.7 is required to build")
  endif()

As was already pointed out you can simply run make bpy to build Blender as a Python module. This command will automatically set all required variables, no need to worry about it. What is not set is PYTHON_SITE_PACKAGES which can be set after make bpy was called for the first time.

By the way, it's important to follow the instructions and to have the directory structure exactly as described in the official docs:

your_blender_dev_dir/blender
your_blender_dev_dir/lib

(see the doc for more detail)

After calling make bpy another folder, with all the needed scripts and binaries will be generated alongside those other 2 folders. In my case, on Ubuntu it's:

your_blender_dev_dir/blender
your_blender_dev_dir/lib
your_blender_dev_dir/build_linux_bpy    - your new, generated folder.

During the first generation I also caught an exception in the very end of the process(related to PYTHON_SITE_PACKAGES variable):

now run: "make install" to copy runtime files and scripts to PYTHON_SITE_PACKAGES-NOTFOUND/2.90
[100%] Built target blender
Install the project...
-- Install configuration: "Release"
-- Installing: /usr/lib/python3.7/PYTHON_SITE_PACKAGES-NOTFOUND/2.90/scripts
CMake Error at source/creator/cmake_install.cmake:45 (file):
  file INSTALL cannot make directory
  "/usr/lib/python3.7/PYTHON_SITE_PACKAGES-NOTFOUND/2.90/scripts": No such
  file or directory.
Call Stack (most recent call first):
  cmake_install.cmake:45 (include)

Now, this is where ccmake command comes in handy. It's basically just a frontend for cmake that helps you change its input parameters and other configs. Call it in the manner explained by Chgad, but also make sure you are following the hints at the bottom of ccmake console so that you properly configure[c] and generate[g] the corresponding cmake files. I missed one of the commands and as a result cmake files were not regenerated and cmake took variables from its cache on the next run.

In any case, if you managed to set PYTHON_SITE_PACKAGES correctly to where you want it to be(I would recommend system-wide installation because copying all those files into all you virtual envs is a serious burden), you just run make bpy one more time and you are good to go.

Test it with something like:

$python3.7
>>>import bpy
>>>bpy.context.scene.render.engine = 'CYCLES'
>>>bpy.ops.wm.save_as_mainfile(filepath='/tmp/my.blend')

Important note: CYCLES renderer is the only working option to run bpy for now, at least on Ubuntu. See here.

Answer 7

Compiling blender as python module for Windows

This guide is completely fine, just follow the steps closely. If you want to compile some specific release, just change branch in blender repo from master to eg. blender-v2.93-release and run make update to download appropiriate dependencies.

Compiling blender as python module for Linux

Tested on Ubuntu 20.04, with Blender v2.93 release and Python 3.9.5

Be aware that bpy.so will only work with python version that was intended to be used by coresponding blender binary, as explained here in the very bottom Troubleshooting section.

Install Packages

user@user_pc:~$ sudo apt update
user@user_pc:~$ sudo apt install build-essential git subversion cmake libx11-dev libxxf86vm-dev libxcursor-dev libxi-dev libxrandr-dev libxinerama-dev libglew-dev
sudo apt install libwayland-dev wayland-protocols libegl-dev libxkbcommon-dev libdbus-1-dev linux-libc-dev

Download Sources & libraries

0. Move to some work folder, for us it will be ~/Documents. Create blender-git folder for source files and lib folder for dependencies.

   user@user_pc:~$ cd Documents
   user@user_pc:~/Documents$ mkdir blender-git
   user@user_pc:~/Documents$ cd blender-git
   user@user_pc:~/Documents/blender-git$ mkdir lib
   

Following steps can be done concurrently, as they are independent and will take some time

1. cd into blender-git folder and clone blender repository

   Edit, based on batFINGERs comment:

   You can use --depth=1 git flag to make downloading process faster, as it make clone 'shallow', see documentation.

   user@user_pc:~/Documents/blender-git$ git clone https://git.blender.org/blender.git
   

2. open new terminal window in ~/Documents/blender-git and cd into lib and download blender dependencies

   user@user_pc:~/Documents/blender-git$ cd lib
   user@user_pc:~/Documents/blender-git/lib$ svn checkout https://svn.blender.org/svnroot/bf-blender/tags/blender-2.93-release/lib/linux_centos7_x86_64
   

After git finishes downloading

3. cd into newly cloned blender source repository and change current branch to v2.93 release branch

   user@user_pc:~/Documents/blender-git$ cd blender
   user@user_pc:~/Documents/blender-git/blender$ git checkout blender-v2.93-release
   

Wait unitl svn (point 5.) finishes downloading and close it's terminal window

4. Ensure You have right libraries and sources by running

   user@user_pc:~/Documents/blender-git/blender$ make update
   

5. Open ~/Documents/blender-git/blender/CMakeLists.txt in your favorite text editor. Find and change following options:

   • WITH_MEM_JEMALLOC to OFF
   • WITH_AUDASPACE make sure its ON
   • WITH_PYTHON_INSTALL to OFF
   • WITH_PYTHON_MODULE to ON

   then save and quit.

6. run make

   user@user_pc:~/Documents/blender-git/blender$ sudo make
   

   it should build all libraries, and it's very likely to fail with following error:

   /usr/bin/ld.gold: error: /usr/lib/x86_64-linux-gnu/libpng.a(pngerror.o): requires dynamic R_X86_64_PC32 reloc against 'stderr' which may overflow at runtime; recompile with -fPIC
   collect2: error: ld returned 1 exit status
   make[3]: *** [source/creator/CMakeFiles/blender.dir/build.make:534: bin/bpy.so] Error 1
   make[2]: *** [CMakeFiles/Makefile2:7272: source/creator/CMakeFiles/blender.dir/all] Error 2
   make[1]: *** [Makefile:163: all] Error 2
   make: *** [GNUmakefile:345: all] Error 2
   

   if it does, it's "fine", we expected it. If it didn't it's great, move to point n. to see how to install compiled blender. If different errors occurs, contact me, we will see whether I can help.

7. Now, error we encountered is caused by libpng.a not being compiled with -fPIC flag, its somewhat explained here. The solution is to compile it yourself, or use version compiled with -fPIC. 8, To compile it yourself, see this answer. For now we will assume that u have precompiled version, for example from here.

8. Download libpng.tar.gz, for example into ~Documents/libpng folder

9. Open new terminal window in /usr/lib/x86_64-linux-gnu and run

   user@user_pc:/usr/lib/x86_64-linux-gnu$ sudo mv libpng.a libpng_no_pic.a
   user@user_pc:/usr/lib/x86_64-linux-gnu$ sudo cp ~/Documents/libpng/lib/libpng.a libpng.a
   

   it will rename current libpng.a into libpng_no_pic.a and copy new libpng.a in its place.

10. Now we can again use our old terminal window form ~/Documents/blender-git/blender and re-run make. It won't need to recompile all the dependencies, and should be pretty quick.

    user@user_pc:~/Documents/blender-git/blender$ sudo make
    

    If it succeeds, following file should exist: ~/Documents/blender-git/build_linux/bin/bpy.so if it doesn't, it means that something has gone wrong.

11. Now copy all the files and 2.93 folder from ~/Documents/blender-git/buld_linux/bin into site-packages folder of Your python installation.

This answer may get outdated after some time. You can check out this repo where bpy.so is part of dependencies, so guides there are likely to be more up-to-date than this post.

Answer 8

If all you want is a "fake" version of blender's libraries so you can code bpy in an IDE with autocomplete, I'm currently using THIS open source library. It takes a running version of blender and strips out all of the data types and available functions.

Once downloaded it can be run with the following bash script with the paths changed to what they are on your local machine.

"PATH_TO_BLENDER\Blender.exe" -b -P "PATH_TO_PYTHONFILE\pypredef_gen.py"

The generated python files can be brought into your IDE and whereas they provide no functionality (The final script needs to be run in blender) you can code within your IDE of choice with autocomplete.

Answer 9

may be you can try:

pip install fake-bpy-module-<version>
#Then you can
import bpy

fake bpy github link

Answer 10

I had a lot of troubles with installing bpy, until I figured out that you have to set CMAKE_INSTALL_PREFIX to /usr/lib/python3.7 and not to site-packages. Also in virtual environments, take the root folder of the venv and not site-packages.