How do you integrate py5 into JupyterHub?

[BigFlagBurito]

Hello,

I am trying to get py5 to run in JupyterHub, but the instructions do not make it clear whether the functionality is supported for JupyterHub.
I have installed py5, py5[extras] and py5jupyter.
Both kernels are running:

• python -m py5jupyter.kernels.py5.install --sys-prefix
• python -m py5jupyter.kernels.py5bot.install --sys-prefix

When I start the Quick Example with the Python kernel, I get the following error:
py5 is unable to run correctly in headless mode. Make sure you are running in a graphical environment and that your Java Virtual Machine is not a Headless JVM.

Afterwards, I tested the py5 kernel with this example and received the following error:
name 'run_sketch' is not defined

There are no errors in the user's log.
Are there other things that need to be installed or configured, or is there no functionality for this with JupyterHub?
Thank you very much for your help.

Java-Version:

openjdk version "21.0.8" 2025-07-15
OpenJDK Runtime Environment (build 21.0.8+9-Ubuntu-0ubuntu122.04.1)
OpenJDK 64-Bit Server VM (build 21.0.8+9-Ubuntu-0ubuntu122.04.1, mixed mode, sharing)

[hx2A]

Hi @BigFlagBurito ! Thank you for your question.

In the early years of py5 I was adamant about getting py5 to work well in Jupyter and JupyterHub / Google Colab. py5 does work well in Jupyter, but JupyterHub implies running Sketches on a server and interacting with them from a local computer. The problem there is you can't really see animations running on a server. I did build a "Sketch Portal" that let me see a running Sketch that worked reasonably well but it broke due to upgrades in Jupyter. I haven't had time to rebuild that and have been focused on other priorities. There isn't that much interest from the community in running py5 this way.

@villares and I have worked on this before and @villares has a Google Colab notebook that a year ago was able to install and run py5. It isn't working right now though - Google has changed things that undermine py5 and I don't see why.

But, if you have your own Jupyter Lab server, here are some things you need to know to get it working.

First, you need to install the jvm. Some jvm installs are "headless" and will never work for py5. The jvm that comes with your server might already be headless. You can make sure you install the proper one with this:

!pip install install-jdk --quiet
!python -c "import jdk; print('Java installed to', jdk.install('21'))"

Next you must install some things that Processing will need to run on linux, plus a virtual frame buffer (xvfb).

!apt-get -qq install ca-certificates-java libxcursor1 libxrandr2 libxrender1 libxtst6 libxi6 xvfb

Next you must start the virtual frame buffer. If you don't this you'll get that headless error, even if your installed jvm is not headless.

!nohup /usr/bin/Xvfb :0 -screen 0 1024x768x24 &
%env DISPLAY=:0

Install py5. Don't install any dependency that also might try to upgrade Jupyter or IPython, that can mess up JupyterHub. py5[extras] might do that so lets skip py5jupyter for now, until we get the basics working for you.

!pip install py5

Now try it out:

import py5
import py5_tools

def setup():
  py5.size(500, 500)
  for _ in range(500):
      py5.fill(py5.random_choice(('red', 'green', 'blue')), 100)
      py5.square(py5.random(50, 450), py5.random(50, 450), py5.random(10, 30))

In the next cell:

py5_tools.screenshot()

Don't forget to exit the Sketch:

py5.exit_sketch()

Does this help?

[villares]

Wow! I was unaware that Google Colab changed and broke the example, I really don't use it much, it was more of a proof of concept...

So, I managed to find some settings to make Google Colab work in a 2025.10 runtime mode, and added that information to the notebook: https://colab.research.google.com/drive/1rI1Oav9aT6qLdvwFkN9gzzVLath2vEI_?usp=sharing

[BigFlagBurito]

Thanks, py5 is pretty new to me and I usually only manage JupyterHub.
I had to make one change, then I had an image after screenshot.
I had to run nohup like this.

import os
os.system("nohup /usr/bin/Xvfb :0 -screen 0 1024x768x24 &")

There was a warning? It worked anyway.
_XSERVTransmkdir: ERROR: euid != 0,directory /tmp/.X11-unix will not be created.

[BigFlagBurito]

I have tried to create more than just an image, but unfortunately I have failed.
My users would like to use py5 with interactions (mouse clicks, sliders, etc.), but if I understand correctly, this is not possible because sketch_portal has been removed?

[hx2A]

@BigFlagBurito sorry for the slow reply

My users would like to use py5 with interactions (mouse clicks, sliders, etc.), but if I understand correctly, this is not possible because sketch_portal has been removed?

The sketch_portal was removed because it no longer worked. It stopped working as Jupyter changed. It was never perfect though. It could get a good frame rate but only if the size of the Sketch was on the small side and you had a good network connection with the server.

Getting it to work again with the existing architecture wasn't a good idea. There is a path forward but I didn't think there was any interest from users. Since you have asked about it, I will count this as a vote for me to revisit the Sketch portal.

I do understand the value of Python in the browser. Someday I will make this happen!