How to install python libs in Blender (part 1)

EDIT 2020: This series is now obsolete since Blender 2.80. Please see this answer on StackExchange. Here is a possible function to install modules inside Blender, provided you can modify the Blender directory:

import subprocess

def install_pip_dep(module_name):
    python_path = bpy.app.binary_path_python
    subp = subprocess.run([python_path, "-m", "ensurepip"])
    if subp.returncode != 0:
        return False
    subp = subprocess.run([python_path, "-m", "pip", "install", module_name])
    if subp.returncode != 0:
        return False
    return True

if __name__ == '__main__':
    install_pip_dep("triangle")

---

In this article, we share some tips to install third-party python libraries for your scripts and add-ons. This is the easy way, when the library exists on repositories accessible to package managers such as pip.

Introduction

Oftentimes, like many Blender users, I find myself needing features not included in either Blender or Python. As much as I’d like to implement them in the C sources and offer patches to the developer team, I’m just not able to, and most of the time it wouldn’t make sense anyway. I am, however, sufficiently proficient in Python to write add-ons, which have so far fit my needs very well. Last year I started learning a bit of image processing beyond basic compositing, and needed to manipulate image pixels directly. Again, some operations might have been implemented as nodes in the compositing module, but for the most part it’s just too mathematically limiting. Python itself offers access to most of Blender’s data, including geometry, texture settings and image pixels. On the other hand, one can manipulate such data using numpy, included with Blender. So the natural thing to do is to access data from python, process them using numpy, and push them back to Blender.

The problem is, sometimes Python and numpy just aren’t enough. You may need to do more advanced processing, for which you’d either need to write thousand-line functions, or leverage countless free libraries available from the Python Package Index (PyPI), or elsewhere. Most of these libraries are released under GPL-compatible licenses, which means they can be linked (used) in a script.

If you’ve ever installed add-ons in Blender, you may be familiar with the addons directory, located in the config for the current version (eg. ~/.config/blender/2.79/scripts/addons on some unix-like systems). addons is in the Python path in Blender. ¹

In the same way that you can install add-ons, you can also install modules, libraries used by Python scripts to extend features. A modules directory is located next to the addons one in the config path.

For instance, if you’d like to install Beautiful Soup, an XML and HTML parser, you might be tempted to download the sources and install them directly, something like:

bash
#!/bin/bash
wget https://www.crummy.com/software/BeautifulSoup/bs4/download/4.6/beautifulsoup4-4.6.0.tar.gz
tar -xvzf beautifulsoup4-4.6.0.tar.gz
cp -r beautifulsoup4-4.6.0/bs4/ ~/.config/blender/2.79/scripts/modules

Don’t bother trying this though, because unfortunately, even for a “simple” library such as Beautiful Soup (a few files, pure Python), this will not work: if you try to import bs4, an error message pops up, saying that the module is for Python 2, whereas Blender uses Python 3. That is why we need pip: it can compile or otherwise alter the sources prior to installation.

The simple case: using pip

Pip is a Python package manager, which can download, extract, compile and install modules, mainly from the PyPI repository. The basic usage is pip install. However this doesn’t work out of the box for us, because Blender uses its own Python distribution, and pip installs modules either in the system, or user path, which are not scanned by Blender.

One more thing before we actually get to installing the lib proper. It is generally advised against to use pip to install python modules system-wide, because it may screw up dependencies, paths, etc. So on Linux we may use virtual environments, which are a way to isolate the whole python runtime in a self-contained directory. This article isn’t meant to be a full walkthrough, but in a nutshell, after installation (which depends on the platform), you create a virtual environment thus:

#!/bin/bash
virtualenv -p python3 venv
source venv/bin/activate

The first command specifies the python executable (here, python3 because that’s the version that Blender ships with), and destination. You then activate the environment, so that all further installations go into the venv dir.

So now, we can pip install beautifulsoup4, and it will go into venv/lib/python/site-packages/. Then, we can do:

#!/bin/bash
cp -r venv/lib/python3.5/site-packages/bs4/ ~/.config/blender/2.79/scripts/modules

Start blender, import bs4, and voilà! the module is installed, ready to parse like crazy.

I am aware that this may not be very accessible to non-technical users, but it is so far the simplest, cleanest way I’ve found to install libs, to be used in Blender scripting. Another way might be to extend the sys.path directly in Python, but this has the drawback of depending on the platform and environment, and may force the user to either use environment variables, or modifiy scripts to include the right paths. This makes it much harder to maintain scripts, hence the modules way.

In a following article, I will tackle another difficulty I encountered upon installing external libraries: incompatible versions of Python, and how to overcome them.