Processing → py5 (SR) → Installing py5 on Windows and Linux
Installing the py5 library — Windows and Linux
if setting up Java and JAVA_HOME by hand is too much for you, use the py5 plug-in for Thonny (SR) – it downloads and sets up Java by itself.
You need: Python 3 + Java 17/21 + py5
Before installing py5, it is important to check whether Python 3 and Java are already installed.
py5 does not run in the MicroPython environment on the micro:bit, but on the computer, in a standard Python 3 environment.
py5 requires:
- Python 3
- Java 17 or Java 21
- a correctly set
JAVA_HOME
1. Checking the Python 3 installation
Open a terminal:
- on Windows: Command Prompt or PowerShell
- on Linux: Terminal
Type:
python --version
or:
python3 --version
If everything is fine, you will see something like:
Python 3.11.8
If you get a message that Python does not exist, you must first install Python 3 from the official site. On Windows be sure to tick the option: Add Python to PATH On Linux Python 3 is often already there, but it is a good idea to check the version before installing py5.
Linux: how to install Python 3 if it is missing
On Zorin, Ubuntu and similar distributions Python 3 usually comes already installed. If it does not, you can install it from the terminal:
sudo apt update
sudo apt install python3 python3-pip
After that, check again:
python3 --version
pip3 --version
If these commands return versions, the Python environment is ready.
2. Checking the Java installation
Next, check the Java version:
java --version
It is recommended that you use:
- Java 17
- or Java 21
py5 requires Java 17 or newer, and Java 11 is not enough for reliable work.
If you have several Java versions on your computer, py5 will use the one that is correctly set through
JAVA_HOME and the system PATH.
Linux: how to install Java 21 if it is missing
On Linux the simplest way is to install the JDK with the package manager. On Zorin and Ubuntu-based systems use:
sudo apt update
sudo apt install openjdk-21-jdk
Then check:
java --version
If you see Java 21, the installation was successful.
For py5 the safest choice is Java 21, because Java 25 has turned out not to be a good choice for this tool.
3. Checking JAVA_HOME
On Windows check:
echo %JAVA_HOME%
On Linux check:
echo $JAVA_HOME
If everything is set correctly, you should get the path to the JDK installation.
For example:
C:\Program Files\Eclipse Adoptium\jdk-21.0.x
or on Linux something like:
/usr/lib/jvm/java-21-openjdk-amd64
If
java --version works, but JAVA_HOME is not set,
py5 may still report an error.
That is why both checks are important.
Linux: how to set JAVA_HOME temporarily or permanently
If JAVA_HOME is not set, you can add it to your profile.
First find out the exact path to the JDK folder:
readlink -f /usr/bin/java
The path you get usually leads to something like:
/usr/lib/jvm/java-21-openjdk-amd64/bin/java
Then JAVA_HOME is:
/usr/lib/jvm/java-21-openjdk-amd64
A temporary setting for the current terminal:
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
You can write a permanent setting into the file:
~/.bashrc
at the end of the file add:
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
Then load the changes:
source ~/.bashrc
If you use Zorin with a different shell, the change may need to go into the corresponding profile file. For most users
~/.bashrc is enough.
4. Installing py5
Windows
In Command Prompt or PowerShell type:
pip install py5
If you have several Python versions, this is safer:
python -m pip install py5
If you use a particular Python interpreter, you can give its full path, for example:
"C:\path\to\python.exe" -m pip install py5
Linux
On Linux it is most often:
pip3 install py5
or:
python3 -m pip install py5
If you want to be completely sure that the installation is done in the right Python 3 environment, the safest variant is:
python3 -m pip install py5
If you get a permissions error, do not start changing your code. First check whether you are using the right Python 3 and whether
pip3 is installed.
If pip3 is missing on the system, install it like this:
sudo apt install python3-pip
Linux: if you use a virtual environment
On some computers it is useful to install py5 in a virtual environment. This prevents the system and the projects from getting mixed up.
python3 -m venv py5-env
source py5-env/bin/activate
pip install py5
After activation, the name of the environment appears in the terminal, and all packages are installed only for that project.
If you want to have several projects on one computer, a virtual environment reduces conflicts between libraries.
5. Installing additional packages
For serial communication with the micro:bit you often also need:
pip install pyserial
On Linux:
pip3 install pyserial
or in an activated virtual environment:
pip install pyserial
pyserial is useful when a py5 program needs to read data from the serial port.
If you are working on a micro:bit + py5 project, install
pyserial right away too.
It will make connecting to the device easier later.
6. Testing the py5 installation
When the installation is finished, test it:
import py5
print("py5 works")
If there is no error, the installation was successful.
Then try a simple graphical example too:
import py5
def setup():
py5.size(400, 400)
def draw():
py5.background(220)
py5.circle(200, 200, 100)
py5.run_sketch()
If a window with a circle appears, py5 is ready to use.
Linux: if the window does not open
If the test program does not open a graphical window, check the following:
- whether
JAVA_HOMEis set correctly - whether Java 17 or 21 is installed
- whether you installed py5 into the same Python 3 you use to run the program
- whether the terminal of the virtual environment is active, if you use one
py5 is installed, but Java is not found or
JAVA_HOME
is set to the wrong version.
7. What should you pay attention to?
- py5 works with the standard Python 3 interpreter
- MicroPython on the micro:bit is not the same as Python 3 on the computer
- Java 17 or 21 is the recommended version
JAVA_HOMEmust point to the right JDK- if you have several Python versions, check exactly which one you are using
- on Windows you must not mix up Thonny's Python, the system Python and the Python from PATH
- on Linux check that you are using
python3andpip3, not older or system variants
py5 is installed, but in a different Python from the one that runs in the editor. That is why you should always check:
python --versionpython -m pip show py5import sys; print(sys.executable)
python3 --versionpython3 -m pip show py5python3 -c "import sys; print(sys.executable)"
8. A short overview for Windows and Linux
| Step | Windows | Linux |
|---|---|---|
| Checking Python | python --version |
python3 --version |
| Checking Java | java --version |
java --version |
| Checking JAVA_HOME | echo %JAVA_HOME% |
echo $JAVA_HOME |
| Installing py5 | python -m pip install py5 |
python3 -m pip install py5 |
| Installing pyserial | python -m pip install pyserial |
python3 -m pip install pyserial |
If Python 3, Java 17/21 and JAVA_HOME are set correctly, installing py5 usually goes without problems. After that you can use py5 for:
- drawing
- animations
- interactive projects
- communication with the micro:bit
