Upgrading your OctoPrint install to Python 3

If you are still running Python 2 and using OctoPrint 1.7.0+, you will start to see warnings like this:

You need to upgrade your OctoPrint install to use Python 3, as Python 2 is end-of-life and a future OctoPrint version will no longer support running using Python 2. In addition, there's at least 39 plugins that already don't support Python 2 and more will follow, that you won't be able to take advantage of. You should upgrade as soon as possible.

How can I upgrade?

The process is slightly different depending on how you are running OctoPrint. Select how you have OctoPrint running below to find out how to upgrade:


There's two options to upgrade your OctoPi install to Python 3:

  1. Installing OctoPi 0.18, released in January 2021, which runs OctoPrint using Python 3 by default.

    To install OctoPi 0.18 on your Raspberry Pi:

    :spiral_notepad: Note: You will need to update OctoPrint before you can reinstall your backup, otherwise there is a version mismatch as OctoPI 0.18 ships with OctoPrint 1.5.2.

  2. If you are using OctoPi 0.17 (only) then you can use the upgrade script, which will attempt to move your OctoPrint install from Python 2 to Python 3. This is only compatible with OctoPi 0.17 as earlier versions can't install the newer versions of Python required (3.6+).

    Please follow the instructions on the Upgrade to Python 3 script's homepage to get your OctoPi 0.17 install upgraded to use Python 3.

Manual install (Linux)

Raspberry Pi OS or other Debian based distros (eg. Ubuntu)

Manual installs on Linux can be upgraded *if you have Python 3.6 or newer already installed, by using the Upgrade Script. Python 3.6 or newer needs to be installed as python3, for more details please see how to use the script on it's homepage.

If you can't install Python 3.6+ on your OS, you should look into upgrading the OS used to a newer version that can install newer versions of Python - 3.6 has been available since 2016.

Other distros

The upgrade script mentioned above is tested on Raspberry Pi OS & Ubuntu, so that's all it's guaranteed to work with. If someone would like to fork the script above & edit it to work on other distros (eg. Fedora), then I would be more than happy to incorporate it into this guide.

Manual install (Windows/MacOS)

On both Windows and MacOS there is no automated script, you will have to reinstall the virtual environment yourself.

Refer back to the OS-specific install guides for how to setup the virtual environment and install OctoPrint. All settings and configuration would be saved, but you will have to reinstall plugins.

Other installs

If your system is not supported, for example you cannot install Python 3 on the system, then you should look at upgrades that will enable you to do so. Python 2 was end-of-life at the start of 2020, so if you are using an OS where that is your only option then it too is probably out of support and needs upgrading.

Performing the actual upgrade of OctoPrint to Python 3 will have to be done manually.

Why can't an upgrade to Python 3 be performed automatically?

For OctoPrint to upgrade it's Python version, it would be like destroying the floor underneath you. OctoPrint runs in Python, so it can't change that itself. This is why an external upgrade script is required, to make it as easy as possible if you don't want to reflash the OS.

It also depends on the version of Python installed on the system. For example, the highest Python version OctoPi 0.16 can use is 3.5, which is too old to run OctoPrint on. OctoPi 0.17+ use Python 3.7 which is supported.


Need help upgrading to Python 3?

Please open a new topic on the forums, rather than commenting here