Migrating to pyproject.toml and build isolation¶

Python’s packaging has come a long ways in recent years with regards to getting modernized. The old setup.py based approach of configuring your package for packaging has been replaced by a pyproject.toml that supports a whole lot more build systems beyond setuptools as well as configuring the various development tools that are part of the Python ecosystem. In addition to that, current versions of pip (25.3+) by default install packages - including OctoPrint plugins - in what’s called “build isolation”, to ensure less of a dependency nightmare by building an installable “wheel” for a package in an isolated environment with the barest minimum of dependencies, as defined by the package.

This build isolation causes issues with OctoPrint plugins that still use the old setup.py based plugin template, as that requires a dependency provided by OctoPrint during installation - when build isolation is active, that cannot be pulled in and the installation fails. Thankfully, pip provides a workaround in the shape of the parameters --use-pep517 --no-build-isolation and OctoPrint 1.11.4+ detects automatically whether these parameters are needed to install or update a plugin package.

However, it would be good if plugin developers make sure their code gets updated to more modern tooling. Not only has it various advantages, all of Python’s ecosystem is fully going into that direction and long term even the above workaround might at some point vanish. We don’t know, so we should modernize!

With octoprint-plugin-tool there’s a quick solution to migrate most plugins still using the legacy packaging approach to a more modern setup.

Obtaining octoprint-plugin-tool¶

octoprint-plugin-tool is available on the official Python package Index PyPI and thus can easily be obtained through pip:

pip install octoprint-plugin-tool

Alternatively, you may also run it directly through pipx run:

pipx run octoprint-plugin-tool

or uv tool run:

uv tool run octoprint-plugin-tool

Note that it requires Python 3.9 and newer.

OctoPrint 1.12.0 will also include it and offer its functionality on its command line:

octoprint dev plugin:migrate-to-pyproject

How to use octoprint-plugin-tool¶

In most cases, migrating your plugin to pyproject.toml is as easy as running

octoprint-plugin-tool to-pyproject --path /path/to/your/plugin/checkout

That will do the necessary conversion steps and you’ll end up with a modified source tree that should already work fine.

If there’s any reason the tool cannot do the migration, it will tell you why. Also take note of any warnings and instructions on how to proceed it outputs.

It is strongly advised to test packaging and installing your plugin now the way you usually would. Once you are satisfied everything is still working like it should, release your changes as a new version of your plugin.

Further reading¶