Skip to main content

Blender distutils addon

Project description

This Python module adds a new command to distutils to build Blender addons: bdist_blender_addon. It also provides a simple mechanism to package extra modules not included with Blender’s Python distribution within the addon.


See the info_example_distutils addon to see how this distutils module is used.


Installing the blender.distutils module

The module is available on PiPy and installable with pip.

$ pip install blender.distutils

It is suggested to add a requirements.txt file to the Blender addon plugin that lists the module dependencies.

# This is requirements.txt

# This module adds the bdist_blender_addon command


# This module is required by the addon, but not distributed with blender
# bdist_blender_addon will ship it if with the addon
# Dependencies to be included are listed in setup.cfg


Add a simple to the blender addon

The bdist_blender_addon is a distutils command. As such, a file is required. Addon name and version are defined by this file. I suggest using bumpversion to keep, bl_info and your git tags in sync.

The for a blender addon is actually quite straightforward. The install_requires argument should only list the first-level dependencies needed by the addon: those may require their own dependencies. The actual modules to be shipped with the addon are cherry picked in setup.cfg.

from setuptools import setup, find_packages

    description='Blender example distutils',
    author='Charles Flèche',
        'Development Status :: 5 - Production/Stable',
        'Intended Audience :: End Users/Desktop',
        'Topic :: Multimedia :: Graphics :: 3D Modeling',
        'Topic :: Multimedia :: Graphics :: 3D Rendering',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3 :: Only'

    # Here are listed first level dependencies needed by the module. Themselves
    # may require dependencies. The actual modules to be shipped with the addon
    # are cherry picked in setup.cfg

Including third-party modules not shipped with blender

The bdist_blender_addon command allows to include additional python modules that are not shipped with Blender. These modules will be included in the root folder of the addon. Currently an explicit list of modules, including their dependencies, needs to be configured.

Cherry pick the modules to be shipped with the blender addon

The modules to be included to the blender addon are listed as an option of the [bdist_blender_addon] section in setup.cfg. This list includes all the modules and their dependencies.

# This is in setup.cfg


# Here are listed the modules (and their dependencies) to be shipped
# with the blender module. In this example the addon requires `dateutils`,
# which in turns requires `dateutil`, `pytz` and `six`.
addon_require = dateutil,dateutils,pytz,six

Include the additional modules folder in the addon code

The addon needs to explicitly register the path to third party modules. During development, those modules will be in a virtual environment. When the addon is installed in production, those modules will be at the root of the addon folder.

import pathlib
import os
import site
import sys

def third_party_modules_sitedir():
    # If we are in a VIRTUAL_ENV, while developing for example, we want the
    # addon to hit the modules installed in the virtual environment
    if 'VIRTUAL_ENV' in os.environ:
        env = pathlib.Path(os.environ['VIRTUAL_ENV'])
        v = sys.version_info
        path = env / 'lib/python{}.{}/site-packages'.format(v.major, v.minor)

    # However outside of a virtual environment, the additionnal modules not
    # shipped with Blender are expected to be found in the root folder of
    # the addon
        path = pathlib.Path(__file__).parent

    return str(path.resolve())

# The additionnal modules location (virtual env or addon folder) is
# appended here

# This module is not part of the standard blender distribution
# It is shipped alongside the plugin when `python bdist_blender_addon`
import dateutils

Build the module

The bdist_blender_addon command will copy the addon code, copy the additional modules over, clean unneeded files (like the *.pyc bytecode files) and package them all in a versioned zip archive under the dist folder.

$ python bdist_blender_addon
running bdist_blender_addon
running build
running build_py
creating build/lib/info_example_distutils
copying info_example_distutils/ -> build/lib/info_example_distutils
creating build/lib/info_example_distutils/dateutil
[long list of files being copied or added to the addon zip archive]

$ ls dist/

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blender.distutils-1.0.5.tar.gz (4.2 kB view hashes)

Uploaded source

Built Distribution

blender.distutils-1.0.5-py3-none-any.whl (4.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page