Python Wheels#

Python wheels (*.whl) are the standard way of distributing Python modules. They are supported in Blender to make self-contained Python Extensions.

Guidelines#

  • By convention, always locate the files under ./wheels/.

Requirements#

  • Wheels must be bundled unmodified from Python’s package index.

  • Wheels must include their dependencies.

  • Wheels filenames must match Python’s binary distribution specification: see docs. Wheels downloaded from Python’s package index will follow this convention.

  • Use forward slashes as path separators when listing them on the manifest </extensions/getting_started#manifest>.

How to Bundle Wheels#

Python wheels (*.whl) can be bundled using the following steps.

Downloading Wheels

Download the wheel to the directory ./wheels/.

For wheels that are platform independent this example downloads jsmin:

pip wheel jsmin -w ./wheels

For wheels that contain binary compiled files, wheels for all supported platforms should be included:

This example downloads pillow - the popular image manipulation module.

pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=macosx_11_0_arm64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=manylinux_2_28_x86_64
pip download pillow --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=win_amd64

The available platform identifiers are listed on pillow’s download page.

Update the Manifest

In blender_manifest.toml include the wheels as a list of paths, e.g.

wheels = [
   "./wheels/pillow-10.3.0-cp311-cp311-macosx_11_0_arm64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-manylinux_2_28_x86_64.whl",
   "./wheels/pillow-10.3.0-cp311-cp311-win_amd64.whl",
]

Now installing the package will extract the wheel into the extensions own site-packages directory.

Running

Once the extension has been installed you can check the module is being loaded by importing it in the Python console and printing it’s location:

import PIL
print(PIL.__file__)