blender-pyutils 2026.1

Simple utilities for building and installing Python extensions for Blender.

Synopsis

This is a small Python package that installs a command-line utility to facilitate extension installation in Blender. It currently provides the following functionality:

• Validate and build Blender extensions, including their dependency wheels.
• Generate a shell environment file for setting the PYTHONPATH environment variable to match Blender's Python path.
• Print information about Blender and its internal Python environment.
• Install Python packages directly into Blender's modules directory.
• Create a Python virtual environment with the bpy package installed.

Links

GitLab

• Homepage
• Source
• Issues
• Documentation
• GitLab package registry

Other Repositories

• Python Package Index (PyPI)
• Software Heritage

Usage

Install this package, preferably in a Python virtual environment.

# Create the virtual environment.
python3 -m venv

# Activate it.
source venv/bin/activate

# Ensure that pip is installed and up-to-date.
python3 -m ensure pip
pip install -U pip

# Install this package.
pip install -U Blender Python Utils

blender-pytuils Executable

The package will install the blender-pyutils command that accepts different subcommands as arguments.

usage: blender-pyutils [-h] {build,env,info,pip,venv} ...

Utility script for validating and packaging Blender extensions.

positional arguments:
  {build,env,info,pip,venv}

options:
  -h, --help            show this help message and exit

build Subcommand

The build subommand will validate and build a Blender extension. If a requirements.txt file is found in the extension directory then it will also download the dependency wheels to the wheels subdirectory and add them to the blender_manifest.toml.

usage: blender-pyutils build [-h] [-p PATH]

Validate and build an extension. If a requirements.txt file is found in the
extension directory then the wheels for its dependencies will be downloaded to
the wheels directory and the manifest will be updated to include them.

options:
  -h, --help       show this help message and exit
  -p, --path PATH  The path to the extension's root directory. If not given,
                   the current working directory is assumed.

env Subcommand

The env subcommand generates a sourceable shell file that can be used to match the shell's PYTHONPATH environment variable to Blender's internal Python path. Sourcing the file will allow scripts and code editors to find Blender's internal Python packages.

usage: blender-pyutils env [-h] [--example] [-o OUT]

Create a soureable shell configuration file that will set the Python path
environment variable to match Blender's Python path. This will allow scripts
and editors to detect Blender's internal Python modules.

options:
  -h, --help     show this help message and exit
  --example      Mask user name in home directory paths for example output.
  -o, --out OUT  The output path. If not specified, the file will be printed
                 to STDOUT.

Example Output

#!/usr/bin/sh
export PYTHONPATH=/usr/share/blender/5.0/scripts/startup:/usr/share/blender/5.0/scripts/modules:/usr/lib/python314.zip:/usr/lib/python3.14:/usr/lib/python3.14/lib-dynload:/home/user/.config/blender/5.0/extensions/.local/lib/python3.14/site-packages:/tmp/tmp.kaK4D6KGQD/venv/lib/python3.14/site-packages:/tmp/cwd/src:/home/user/dmm/inria/git/user/prometa/src:/usr/share/blender/5.0/scripts/freestyle/modules:/home/user/.config/blender/5.0/scripts/addons/modules:/usr/share/blender/5.0/scripts/addons_core

info Subcommand

The info subcommand will print information about Blender's version, module directory path and configured Python executable.

usage: blender-pyutils info [-h] [--example] [-j]

Print Blender information.

options:
  -h, --help  show this help message and exit
  --example   Mask user name in home directory paths for example output.
  -j, --json  Use JSON output format.

Example Output

Blender module directory: /home/user/.config/blender/5.0/scripts/modules
Blender version: 5.0.1
Python executable: /usr/bin/python3.14
Python path: /usr/share/blender/5.0/scripts/startup:/usr/share/blender/5.0/scripts/modules:/usr/lib/python314.zip:/usr/lib/python3.14:/usr/lib/python3.14/lib-dynload:/home/user/.config/blender/5.0/extensions/.local/lib/python3.14/site-packages:/tmp/tmp.kaK4D6KGQD/venv/lib/python3.14/site-packages:/tmp/cwd/src:/home/user/dmm/inria/git/user/prometa/src:/usr/share/blender/5.0/scripts/freestyle/modules:/home/user/.config/blender/5.0/scripts/addons/modules:/usr/share/blender/5.0/scripts/addons_core
Python version: 3.14.3

{
  "Blender module directory": "/home/user/.config/blender/5.0/scripts/modules",
  "Blender version": "5.0.1",
  "Python executable": "/usr/bin/python3.14",
  "Python path": "/usr/share/blender/5.0/scripts/startup:/usr/share/blender/5.0/scripts/modules:/usr/lib/python314.zip:/usr/lib/python3.14:/usr/lib/python3.14/lib-dynload:/home/user/.config/blender/5.0/extensions/.local/lib/python3.14/site-packages:/tmp/tmp.kaK4D6KGQD/venv/lib/python3.14/site-packages:/tmp/cwd/src:/home/user/dmm/inria/git/user/prometa/src:/usr/share/blender/5.0/scripts/freestyle/modules:/home/user/.config/blender/5.0/scripts/addons/modules:/usr/share/blender/5.0/scripts/addons_core",
  "Python version": "3.14.3"
}

pip Subcommand

The pip subcommand will install Python packages directly to Blender's modules directory. It accepts the same commands as pip.

# Example: install scipy using pip
blender-pyutils pip install scipy

# Example: install scipy using uv
blender-pyutils pip --uv install scipy

# Example: use "--" to pass through options to pip, such as a requirements.txt file
blender-pyutils pip -- install -U -r requirements.txt

usage: blender-pyutils pip [-h] [--path PATH] [--uv] <PIP ARG> [<PIP ARG> ...]

Install Python packages to Blender's module directory. Additional arguments as
passed through to pip.

positional arguments:
  <PIP ARG>    Arguments to pass through to pip. Precede these arguments with
               "--" if any of them begin with "-".

options:
  -h, --help   show this help message and exit
  --path PATH  Installation directory for Python packages. If not given, the
               default Blender module directory will be used. Use the "info"
               command to show the path to the module directory.
  --uv         Use "uv pip" instead of pip.

Caveats

• At the time or writing, Blender does not recognize packages installed with pip's editable option (-e/--editiable).
• Packages must be installed before launching Blender.

Legacy Script

This repository originally only provided blender-pip_install.sh as a wrapper around pip install and uv pip install. It has been superceded by blender-pyutils pip and users should migrate accordingly.

venv Subcommand

The venv subcommand will create a Python virtual environment with the bpy PyPI package installed. It will try to match the version to the local Blender installation. It will also ensure that the virtual environment uses the required version of Python to install the package, even if this version is different from the one used internally by the local version of Blender. This mismatch may occur when packages modifify the Blender package to work with a different version of Python, despite each release of Blender officially supporting only a single version of Python.

usage: blender-pyutils venv [-h] path

Create a Python virtual environment with the PyPI bpy package installed. This
will try to match the version to the currently installed version of Blender
but it will default to the latest version if the installed version cannot be
found. The created virtual environment will also use the version of Python
required by the bpy package. Officially, Blender only supports a single
version of Python with each release but packagers sometimes patch Blender to
work with different versions.

positional arguments:
  path        The virtual environment path.

options:
  -h, --help  show this help message and exit