Before proceeding, you should know that this is a new project with documentation and setup instructions that are a bit rough around the edges. Additionally, there a few issues with Mac (OSX) computers. And finally, you should also know that this project is currently maintained by only one person, and in my free time.
I have tested these instructions on Linux, Windows, and OSX, so I believe this will work for most people. Nevertheless, getting this working might not go smoothly for you. If that’s the case, please be patient and try to work through it or let me know and I’ll do what I can to help. If you hit a snag and figure out a solution, tell me about it and I’ll update the documentation to share what you’ve learned.
There are known issues using py5 on Mac computers. Mac users should read the Special Notes for OSX Users page for more information.
Below are the basic requirements for using py5.
I know that you may not have Java 11 or Python 3.8 on your computer and that Cairo can be difficult to install on non-Linux machines. If this applies to you, I recommend making your life easier by trying the Anaconda Setup.
If you already have Java 11 and Python 3.8+ available on your computer, you can install py5 with the below command.
pip install py5
You can optionally install Cairo and CairoSVG to enable py5’s extra SVG support. If you like using Jupyter Notebooks, consider installing one or both of py5’s Jupyter Notebook Kernels: py5 kernel and py5bot.
Here is a quick py5 example to test that everything works.
import py5 def setup(): py5.size(200, 200) py5.rect_mode(py5.CENTER) def draw(): py5.rect(py5.mouse_x, py5.mouse_y, 10, 10) py5.run_sketch()
You should see a small window that draws squares as you move your mouse around. If that works, have a look at the tutorials for more interesting examples.
Anaconda is a widely used platform for working with Python and the open-source ecosystem. It makes it very easy to create and manage Python environments containing various Python libraries such as py5. Anaconda will also make it easy for you to use other popular Python tools such as Jupyter Notebooks.
First you will need to download the Anaconda Installer for your Operating System. Anaconda’s installation instructions are extensive and should be able to provide the necessary guidance for your computer.
You can create a complete Anaconda environment for py5 using one command:
conda env create -n py5coding -f http://py5.ixora.io/files/install/py5_environment.yml
Feel free to replace
py5coding with your prefered name for the
That environment file contains the below information, telling Anaconda to create an environment with Java 11 (OpenJDK), Cairo, and Jupyter Notebooks.
name: py5coding channels: - conda-forge dependencies: - python=3.8 - cairo - cairosvg - jedi=0.17.2 - jupyterlab - line_profiler - noise - openjdk=11.0.8 - pip - pip: - py5
You can activate the environment using the below command. When the environment
is active, you will see
(py5coding) in the command prompt.
conda activate py5coding
Launch jupyter lab to start coding.
Try testing with the Quick Example to verify everything works.
If the Simple Steps don’t work for you or you want more detailed information, the below steps will provide you with the necessary information to (hopefully) work through any difficulties.
Create Anaconda Environment¶
First you must create an Anaconda environment to install the Python
packages into. Below, we create an environment called
Python 3.8. Note that py5 does not support earlier versions of Python.
Later versions seem to work OK but have not been extensively tested.
The below command will also install the Jupyter Lab tool, which py5 is designed to work well with.
conda create -n py5coding python=3.8 jupyterlab
After creating the
py5coding environment you must “activate” it so
that the subsequent commands take place inside of it. You will know you
are inside the environment because your terminal prompt will change to
include the name of the environment.
conda activate py5coding
You will need to have Java 11 (or later) installed on your computer.
Before attempting the installation, first check to see if you already
have it. You can do this from a terminal or DOS window using the command
The results should be similar to this:
openjdk version "11.0.9" 2020-10-20 OpenJDK Runtime Environment 18.9 (build 11.0.9+11) OpenJDK 64-Bit Server VM 18.9 (build 11.0.9+11, mixed mode, sharing)
If you get an error or see the version number is 1.8 (which is likely for older computers), you will need to install Java. To install it into your Anaconda environment, use the below command.
conda install -c conda-forge openjdk=11.0.8
If you prefer you can download and install Java 11 outside of the
Anaconda environment. There are a lot of tutorials online that will
explain how to do this for your computer. You don’t have to use OpenJDK
if you prefer an alternative. The only important requirement is that the
java -version gives the correct result.
It is important that you have Java 11 installed and available in the Anaconda environment because Processing 4 and therefore py5 both depend on it. If now or in the future you have the wrong version, you will see an error message stating that code “has been compiled by a more recent version of the Java Runtime.”
Be aware that someday Anaconda may want to downgrade your version of
Java when you install some other package. Including the version number
when installing (the
=11.0.8 in the previous command) will prevent
While testing these installation steps and example code, I discovered
that when I installed matplotlib with
conda install matplotlib it
would inexplicably want to downgrade Java 11 to Java 8. Why does it do
this??? Matplotlib does not require Java. One might try circumventing
this issue by installing it with
pip install matplotlib, but
mixing pip and conda installs is not recommended.
It is better to install Java correctly through conda using an explicit version number.
Install Cairo and CairoSVG (optional)¶
Cairo is a drawing library for working with Scalable Vector Graphics (SVG) files. If you complete this optional step, py5 will have the ability to convert SVG images to Py5Image objects using the convert_image() method. As Cairo’s ability to work with the SVG language is more complete than Processing’s, this will provide better support for that image format.
Installing Cairo on Windows or Mac computers is difficult without using an Anaconda environment. To install it with Anaconda, use the below commands. The first installs Cairo and the second installs CairoSVG, which is the Python library that py5 interfaces with to convert SVG images to Py5Image objects.
conda install -c conda-forge cairo
You may get a message saying that it has already been installed. If so, express joy and proceed to the next step.
conda install -c conda-forge cairosvg
Finally, install the py5 library.
pip install py5
If you are on Windows or on a Mac, you may get errors relating to the
dependent noise and line-profiler packages. If so, use one or both of
the following commands to resolve the errors, then try
pip install py5
conda install -c conda-forge noise conda install -c conda-forge line_profiler
Jupyter Notebook Kernels¶
You can optionally install the py5 Jupyter Notebook Kernel. This is a customized Python kernel that will let you write py5 code in Imported Mode. See The Four py5 Modes to learn about the different py5 Modes.
python -m py5_tools.kernel.install --sys-prefix
--sys-prefix argument is optional but I recommend you use it. It
will install the py5 kernel inside the py5 Anaconda environment and
Jupyter will only present it as an option when Jupyter is run in that
You can optionally install py5bot, which is also a Jupyter Notebook Kernel. This is a customized Python kernel that will let you write py5 code in Static Mode.
python -m py5_tools.py5bot.install --sys-prefix
Linux and Windows users may want to use the Thonny
IDE to program with py5. (OSX users need to use
Jupyter Notebooks.) You will need to set the
$JAVA_HOME environment variable so py5 can find your Java Runtime
Environment. To do this, open Thonny Options, and go to the General Tab.
$JAVA_HOME environment variable to the Environment Variables
text box and restart Thonny. See GitHub issue
for more information.
Also consider this blog post by @tabreturn to learn how to use py5 in Imported Mode with Thonny.
Keeping py5 Updated¶
Since py5 is a new library, you can expect frequent updates. Later you will want to upgrade your installation, which you can do with this command:
pip install --upgrade py5