Get started

This guide walks an administrator through deploying Positron Server on JupyterHub. Positron Server reads a license file that you place inside its own install directory, and validates that file with the bundled license-manager binary.

Important

This guide covers Positron Server 2026.09.0 and newer, and 2026.06.1 and older. Positron Server 2026.07.0 through 2026.08.2 validate a signed token instead of a license file, and need the extra setup on the verifier setup page. See the version matrix to confirm which guide applies to the version you install.

Note

To skip the steps on this page, the deployment templates page covers a one-shot install script for The Littlest JupyterHub (TLJH) and a docker-compose template.

What you need from Posit

Send email to academic-licenses@posit.co to request a license file (license.lic). This file is proof of entitlement, and it is the only file this setup needs from Posit.

Positron Server is free for educational use. For the eligibility terms, see the Positron Education License Rider.

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

Take the exact version string from the Positron releases page, then download and unpack the build for your architecture:

Terminal
POSITRON_VERSION=2026.09.0-256       # exact string from the releases page
POSITRON_ARCH=x64                    # x64 or arm64
CDN_ARCH=x86_64                      # x86_64 for x64, arm64 for arm64

curl -L "https://cdn.posit.co/positron/releases/server/${CDN_ARCH}/positron-server-linux-${POSITRON_ARCH}-${POSITRON_VERSION}.tar.gz" \
  -o /tmp/positron-server.tar.gz

mkdir -p /opt/positron-server
tar -xzf /tmp/positron-server.tar.gz -C /opt/positron-server --strip-components=1
Note

Positron spells the CPU architecture three ways. The download filename uses x64 or arm64, the Content Delivery Network (CDN) path uses x86_64 or arm64, and the activation directory uses x86_64 or aarch64. Throughout this guide, <arch> means the activation directory name.

Place the license file next to the license-manager binary, in the activation directory for your architecture:

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

Mode 644 matters. Each single-user session runs positron-server as the student, and positron-server reads and validates this file itself. A root-only mode such as 600 makes every session fail to start.

Confirm the license before you go further:

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

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

Terminal
# for example, in The Littlest JupyterHub
/opt/tljh/user/bin/pip install 'jupyter-positron-server>=0.0.5'

This proxy extension runs as the user. It adds the Positron tile to the JupyterLab launcher and starts positron-server on the first request.

Step 3: Point single-user servers at positron-server

Put positron-server on the session PATH by adding this to jupyterhub_config.py:

jupyterhub_config.py
import os

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

This setup needs no license environment variables. Positron Server finds the license file in its own install directory.

Step 4: Restart JupyterHub

Terminal
systemctl restart jupyterhub

Students can then select the Positron tile in the JupyterLab launcher.

How it works

When a student opens Positron:

  1. jupyter-positron-server kicks off starting Positron Server.
  2. Positron Server validates the license file, and then starts.
  3. jupyter-positron-server opens Positron Server with a connection token for the session.
Single-user server
  jupyter-positron-server    starts positron-server on the first request
  positron-server            validates the license file and starts
  license.lic                mode 644, read by the session

A license file that is missing, expired, or altered stops the session from starting. See Troubleshooting for what each 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, upgrading to 2026.09.0 or newer removes both. 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, and the memory each session needs.
  • Deployment templates covers the TLJH install script and the docker-compose template.
  • Troubleshooting covers a session that does not start.