Upgrading Python for OctoPrint on Raspbian GNU/Linux 10 (Buster)
This guide provides step-by-step instructions on how to upgrade your Python version on Raspbian GNU/Linux 10 (Buster) for use with OctoPrint.
Remember to always back up your OctoPrint data before performing major upgrades or system changes.
For safe and flexible Python version management, especially when dealing with system-critical applications, pyenv is the recommended tool. It allows you to install multiple Python versions and switch between them without affecting your system's default Python installation. This has been tested to work with:
- OctoPrint 1.11.2
- Python 3.12.3
- OctoPi* 0.18.0 (build 2022.08.09.123918)
Using pyenv (Recommended)
This method is the safest as it isolates your OctoPrint Python environment from the system's Python, preventing potential conflicts.
Step 1: Install Prerequisites
First, ensure your system is up to date and install necessary build dependencies for compiling Python.
sudo apt update
sudo apt upgrade -y
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev \
xgcc libgdbm-dev libc6-dev libffi-dev python3-dev python3-pip
Step 2: Install pyenv
Install pyenv using the pyenv-installer script.
curl https://pyenv.run | bash
Step 3: Configure Your Shell for pyenv
Add pyenv to your shell's environment variables. This typically involves adding lines to your ~/.bashrc (for Bash) or ~/.zshrc (for Zsh) file.
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
source ~/.bashrc
If you are using Zsh, replace ~/.bashrc with ~/.zshrc.
Step 4: Install a Stable Python Version (e.g., 3.12.x)
List available Python versions and then install your desired stable version. For example, to install Python 3.12.3:
pyenv install 3.12.3
You can install other stable versions as needed in the same way. For example, to install Python 3.11.6:
pyenv install 3.11.6
Step 5: Verify Python Installation
Check if the newly installed Python version is recognized by pyenv.
pyenv versions
This should list the Python version you just installed.
Step 6: Stop OctoPrint
Before migrating, stop your OctoPrint service. The exact command may vary depending on your OctoPrint installation (e.g., OctoPi, manual install).
sudo systemctl stop octoprint
# Or if you run it manually:
# pkill -f octoprint
Step 7: Install OctoPrint's venv-tool
Download and make the octoprint-venv-tool executable.
curl -LO https://get.octoprint.org/octoprint-venv-tool && chmod +x octoprint-venv-tool
Step 8: Recreate OctoPrint's Virtual Environment
Navigate to your OctoPrint installation directory. This is typically /home/pi/OctoPrint or /opt/octoprint if you followed a standard OctoPi setup or a manual installation guide. You will need to find the path to your OctoPrint virtual environment (e.g., ~/oprint or venv within the OctoPrint directory).
Important: Replace /path/to/your/octoprint/venv with the actual path to your OctoPrint virtual environment and /home/pi/.pyenv/versions/3.12.3/bin/python with the path to the Python executable installed by pyenv.
# Example for OctoPi default venv path and Python 3.12.3
./octoprint-venv-tool recreate-venv /home/pi/oprint --python /home/pi/.pyenv/versions/3.12.3/bin/python
The venv-tool will attempt to reinstall all plugins into the new virtual environment.
Step 9: Start OctoPrint and Verify
Start your OctoPrint service again.
sudo systemctl start octoprint
After OctoPrint starts, open its web interface. In the lower-left corner of the OctoPrint web interface, you should see the Python version it is currently running under. It should now reflect the version you installed (e.g., Python 3.12.3).
Possible Issue: User password invalid for WebUI
Once the web interface is loaded and you encounter a bad username password error you will need to run the following command to reset the passoword for the username you are using.
Activate the virtual environment. On OctoPi:
source ~/oprint/bin/activate
Next run the following command to reset the password for the user you are using.
octoprint user password <user>
# (ex: octoprint user password MyUserName)
It will prompt you for a new password and then set it on the user.
Restart OctoPrint for your changes to take effect, using:
sudo service octoprint restart or similar.
I have tested this on three other installs and all does seem to work, but my setup might be different than yours so always have a backup!
-Enjoy!