Get started

This guide sets up Positron Server on JupyterHub. You install two things in the single-user environment: Positron Server itself, and jupyter-positron-server, which adds a Positron tile to the JupyterLab launcher. Then you add Positron Server to the session PATH and restart JupyterHub.

To skip these steps, use one of the deployment templates. They include an install script for The Littlest JupyterHub (TLJH) and a docker-compose template.

Step 0: Request a license file

Positron Server is free for educational use under the Positron Education License Rider. To request a license file (license.lic), send an email to academic-licenses@posit.co. This file is the only thing you need from Posit.

Step 1: Install Positron Server in the single-user image

Positron Server is available only as a Linux archive from the Posit content delivery network (CDN). It does not appear on the Positron download page or on the GitHub releases page. Download the build that matches the CPU architecture of your single-user servers:

Architecture Download
x86_64 (Intel and AMD) positron-server-linux-x64-2026.10.0-297.tar.gz
ARM64 positron-server-linux-arm64-2026.10.0-297.tar.gz

Then unpack it into /opt/positron-server. To download and unpack from the command line, run the command for your architecture.

For x86_64:

Terminal
curl -L -o /tmp/positron-server.tar.gz https://cdn.posit.co/positron/releases/server/x86_64/positron-server-linux-x64-2026.10.0-297.tar.gz
mkdir -p /opt/positron-server
tar -xzf /tmp/positron-server.tar.gz -C /opt/positron-server --strip-components=1

For ARM64:

Terminal
curl -L -o /tmp/positron-server.tar.gz https://cdn.posit.co/positron/releases/server/arm64/positron-server-linux-arm64-2026.10.0-297.tar.gz
mkdir -p /opt/positron-server
tar -xzf /tmp/positron-server.tar.gz -C /opt/positron-server --strip-components=1

Next, copy the license file into the activation directory, next to the bundled license-manager binary. In the path below, replace <arch> with x86_64 or aarch64.

Terminal
install -m 644 license.lic /opt/positron-server/resources/activation/linux/<arch>/license.lic

The license file needs mode 644. Each session runs positron-server as the student, and positron-server reads the license file itself. With a root-only mode such as 600, every session fails to start.

Before you continue, confirm that license-manager accepts the license file:

Terminal
/opt/positron-server/resources/activation/linux/<arch>/license-manager status

Step 2: Install jupyter-positron-server in the single-user image

Install jupyter-positron-server into the Python environment that runs the single-user server. On TLJH, that environment is /opt/tljh/user:

Terminal
/opt/tljh/user/bin/pip install 'jupyter-positron-server>=0.0.6'

jupyter-positron-server is a jupyter-server-proxy extension. It adds the Positron tile to the JupyterLab launcher, and starts Positron Server the first time a student opens it.

Step 3: Add Positron Server to the session PATH

JupyterHub starts each single-user server with the variables in c.Spawner.environment. Add /opt/positron-server/bin to PATH there, so that jupyter-positron-server can find positron-server:

jupyterhub_config.py
import os

c.Spawner.environment = {
    "PATH": "/opt/positron-server/bin:" + os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin"),
}

You do not need any license environment variables. Positron Server finds license.lic in its activation directory.

Step 4: Restart JupyterHub

Restart JupyterHub to load the configuration:

Terminal
systemctl restart jupyterhub

After the restart, students see a Positron tile in the JupyterLab launcher. To open Positron instead of JupyterLab when students sign in, see Start students in Positron Server.

How it works

When a student selects the Positron tile, jupyter-positron-server starts positron-server inside the single-user server of that student. Positron Server checks license.lic before it starts, so a missing, expired, or altered license file stops the session. When Positron Server is running, jupyter-positron-server opens it in the browser with a connection token for that session.

Troubleshooting shows what each license failure looks like in the logs.

Move an existing deployment off the verifier

If you set up Positron Server 2026.07.0 through 2026.08.2 with the signing key and the Hub verifier service, you do not need either one after you upgrade to 2026.09.0 or later. To remove them, make these four changes:

  1. Change the license file mode from 600 to 644, so sessions can read it.
  2. Remove POSITRON_LICENSE_MINTING_ENDPOINT from c.Spawner.environment.
  3. Remove the positron-license entry from c.JupyterHub.services, and the positron-license-service entry from c.JupyterHub.load_roles.
  4. Delete the signing key at /etc/positron/signing-key.pem, and uninstall jupyter-positron-verifier from the Hub environment.

Next steps

  • Configuration covers the environment variables that jupyter-positron-server reads, landing students in Positron, and limits on memory and CPU.
  • Deployment templates covers the TLJH install script and the docker-compose template.
  • Troubleshooting covers a session that does not start.