Upgrading your OctoPrint install to Python 3

If you are still running Python 2 and using OctoPrint 1.7x, you will see warnings like this:
You are still running Python 2 warning

You need to upgrade your OctoPrint install to use Python 3, as Python 2 is end-of-life and OctoPrint 1.8.0 and later no longer supports running using Python 2. In addition, there's at least 75 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 a new version of OctoPi (0.18+), which runs OctoPrint using Python 3 by default.

    To install the latest OctoPi on your Raspberry Pi:

    • Create a backup using OctoPrint's built-in Backup and restore plugin and download it.

    • Download & Setup the latest OctoPi using the Raspberry Pi Imager.

    • Restore your backup on the new install.

    :warning: On OctoPi 0.18 but also Python 2?

    If your UI already says you are on OctoPi 0.18 but you still get this warning, it means you are
    actually on a development version of OctoPi 0.18 from before it was migrated to Python 3. You'll have to reflash a newer release or alternatively may proceed with the migration instructions for OctoPi 0.17.

  2. If you are using OctoPi 0.17 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.7+).

    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.

    Note that you really only have this option for OctoPi 0.17.0 and some development versions of OctoPi 0.18.0. Any earlier OctoPi versions are not supported, and you will have to manually update your OS (installing a newer build of OctoPi or otherwise).

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.7 or newer already installed, by using the Upgrade Script. Python 3.7 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.7+ on your OS, you should look into upgrading the OS used to a newer version that can install newer versions of Python - 3.7 has been available since 2018.

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. You will need Python 3.7 or newer installed to run OctoPrint.

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. You will need Python 3.7 or newer installed to run OctoPrint.

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+ uses Python 3.7 which is supported.


Need help upgrading to Python 3?

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



Think you can drop this note now - just followed these and OctoPI shipped with 1.7 - might save a step!

1 Like

That's only recently been accomplished through CustoPiZer automation and the raspberry pi imager.