Processing → py5 (SR) → Installing py5 on Windows and Linux


Installing the py5 library — Windows and Linux

An easier way:
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.

Lesson 16 of 17 · MicroPython and micro:bit

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.

What does py5 need?

py5 requires:
  • Python 3
  • Java 17 or Java 21
  • a correctly set JAVA_HOME
If Java is not found correctly, py5 may report an error saying that it cannot start the Java Virtual Machine.

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
Important:

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.

Important:

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.

Recommendation:

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
A check before installing:

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
Note:

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
A practical tip for Linux:

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.

When is a virtual environment useful?

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.

A practical tip:

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_HOME is 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
The most common problem on Linux:

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_HOME must 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 python3 and pip3, not older or system variants
The most common mistake:

py5 is installed, but in a different Python from the one that runs in the editor. That is why you should always check:
  • python --version
  • python -m pip show py5
  • import sys; print(sys.executable)
On Linux use:
  • python3 --version
  • python3 -m pip show py5
  • python3 -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

Finally:

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