blender-pyutils 2025.2

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:

• Print information about Blender and its internal Python environment.
• Validate and build Blender extensions, including their dependency wheels.
• Install Python packages directly into Blender's modules directory.

Links

GitLab

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

Other Repositories

• 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] {info,build,pip} ...

Utility script for validating and packaging Blender extensions.

positional arguments:
  {info,build,pip}

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

info Subcommand

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

usage: blender-pyutils info [-h]

Print Blender information.

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.

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.