# How to build Blender as a Python module?

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?

• Are looking for all of blender as a python module or just "fake version" to be used for coding in an IDE? Aug 29, 2018 at 20:49
• I just want to insert cubes a camera and perform a visibility test. I was thinking of maybe ray casting not sure yet. But yeah not the full blender Aug 29, 2018 at 21:01
• The old wiki pages are still available with a slightly altered URL in blenders archived wiki. It really isn't that different to a normal blender build, mostly you need to enable the WITH_PYTHON_MODULE option. Aug 30, 2018 at 5:44
• I struggled with following the processes on the (archived) blender wiki, but managed to muddle through eventually with the help of this and a few other StackExchange questions. I've written up the full process I used on GitHub here Feb 21, 2019 at 11:30

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.

• Does making such an install interfere if I would already have installed blender normally over apt? My idea is to install blender then test something and if it works to automate it, but I'm not sure if an already existing blender installation over ubuntus package manager would interfere with building it as a python module Aug 31, 2018 at 11:45
• @Hakaishin That shouldn't be a problem, you can install the builded module locally, there shouldn't be any interference Aug 31, 2018 at 14:17
• Do you know maybe if another version of python can be used like 3.6 or does it have to be 3.4? I vaguely remember reading somewhere that it will only work with 3.4 but I'm not sure Sep 3, 2018 at 8:07
• @Hakaishin It should be the same version as is bundled with Blender, so for 2.79b python 3.5.3. You get the version like this Sep 3, 2018 at 8:59
• @Hakaishin Yes, this you can. You can compile Blender with python 3.6, pass -DPYTHON_VERSION=3.6 when configuring CMake. Sep 3, 2018 at 10:40

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 :

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.

• I used make bpy as well but I specified the environment variable PYTHON_ROOT_DIR and let it point to the right python environment in anaconda (here called bpy as well): PYTHON_ROOT_DIR="~/miniconda3/envs/bpy" make bpy. This way, I have blender installed in the right folder directly.
– Jan
Jun 30, 2019 at 7:47
• I needed 'apt-get install libopenexr-dev' to get through the install_deps.sh Aug 4, 2021 at 15:01

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.

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


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.

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.

• Good answer, but this is not my usecase I need to run the code outside of blender Aug 29, 2018 at 21:16
• Ah sorry. I miss-understood from the comments earlier. Aug 29, 2018 at 21:19
• No problem, maybe somebody else wants to do exactly this Aug 29, 2018 at 21:20

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.

may be you can try:

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


# 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

### 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


1. 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/blender$git checkout blender-v2.93-release  #### Wait unitl svn (point 5.) finishes downloading and close it's terminal window 1. Ensure You have right libraries and sources by running user@user_pc:~/Documents/blender-git/blender$ make update

2. 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.

3. 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. 4. 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. 5. Download libpng.tar.gz, for example into ~Documents/libpng folder 6. 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. 7. 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.

8. 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.

• Thankyou, very comprehensive. You don't recommend using install_deps.sh ? Be tempted to mention a shallow clone option, as well as elaborating on python version, as may want this to use with a version other than default. Sep 9, 2021 at 12:42
• Well, honestly I just described how I managed to finally compile blender. I don't really care about which method is correct, because the methods described in numerous internet sources that I came across during the last 2 days, failed me. Also I edited the post do add note about python and blender version and precompiled libpng source. In the same link there are precompiled blender packages for linux and windows, but Im not so sure wheather they will work properly, so Im only mentioning it in this comment. Sep 9, 2021 at 13:04
• NP every bit of info helps Was a regular builder, haven't for a while. It's a great feeling when it finally comes together. Recently UG'd to 20.04. tis very handy to have the real bpy for editing scripts outside blender.. ,might get back to it. Mentioned a shallow git clone --depth=1 as it saves a few gig of download. Sep 9, 2021 at 13:12
• I didn't understand this shallow clone part of your first comment, thanks for the deeper explanation, I have mentioned it, that's a helpful one ^^ Sep 9, 2021 at 13:41

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.

• Can you be more specific with the steps you've made? I'm not very familiar with make/cmake and not sure I'm passing BUILD_CMAKE_ARGS/CMAKE_INSTALL_PREFIX correctly. May 16, 2020 at 21:31