Install & Compatibility
Where this runs
tested against v4.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 75.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 14.2s · import 0.000s · 74MB
76MB installed
● package 76MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ServerProxy
✓ This is primarily configured via `jupyter_server_config.py` using `c.ServerProxy.servers`.
Jupyter Server Proxy is typically configured through Jupyter's configuration system (traitlets in files like `jupyter_server_config.py`) rather than direct Python imports in user application code. Direct imports like `from jupyter_server_proxy.handlers import ProxyHandler` or `from jupyter_server_proxy.config import ServerProxy` are for advanced use cases like building custom extensions or programmatic configuration, not common end-user interaction.
To use jupyter-server-proxy, you typically create a configuration file (e.g., `jupyter_server_config.py`) in your Jupyter config directory (often `~/.jupyter/`). In this file, you define the external processes you want to proxy using the `c.ServerProxy.servers` traitlet. The `command` list specifies how to start the process, with `{port}` being a mandatory placeholder that jupyter-server-proxy replaces with an available port. After configuring and restarting your Jupyter server, the proxied services become accessible via URLs like `<jupyter-url>/proxy/<server-name>/` or through launcher entries in JupyterLab if specified.
import os
# To configure jupyter-server-proxy, create or edit a file like
# ~/.jupyter/jupyter_server_config.py (or another config path)
# Example content for jupyter_server_config.py:
#
# c.ServerProxy.servers = {
# 'my-http-server': {
# 'command': ['python3', '-m', 'http.server', '{port}'],
# 'timeout': 20,
# 'launcher_entry': {
# 'title': 'My HTTP Server',
# 'enabled': True
# }
# },
# 'another-app': {
# 'command': ['sh', '-c', 'echo "Hello, {base_url}/proxy/{port}" > /tmp/output.txt && sleep 99999'],
# 'launcher_entry': {
# 'title': 'Another App',
# 'enabled': True
# }
# }
# }
print("Jupyter Server Proxy is configured via `jupyter_server_config.py`.")
print("Once configured, restart your Jupyter server.")
print("You can typically access proxied services at a URL like:")
print(" <jupyter-url>/proxy/my-http-server/")
print("Or launch from the JupyterLab Launcher if `launcher_entry` is enabled.")
# Example to demonstrate a command that could be run via the proxy (won't actually start here)
# For a real quickstart, this configuration needs to be placed in a .py config file.
# The '{port}' placeholder is crucial and is replaced by jupyter-server-proxy.
example_command = ['python3', '-m', 'http.server', '{port}']
print(f"\nExample command that can be proxied: {example_command}")
Debug
Known issues
breakingVersion 4.0.0 introduced several breaking changes: it now requires Python 3.8+, dropped support for JupyterLab 2, and renamed the JupyterLab extension from `@jupyterlab/server-proxy` to `@jupyterhub/jupyter-server-proxy`.fixEnsure your environment meets Python 3.8+ and JupyterLab 3+ requirements. Update any references to the old JupyterLab extension name.
affects: >=4.0.0
deprecatedThe `nbserverproxy` package is an older version and conflicts with `jupyter-server-proxy`. Installing both can lead to unexpected behavior or errors.fixUninstall `nbserverproxy` before installing `jupyter-server-proxy` using `pip uninstall nbserverproxy`.
affects: All versions when `nbserverproxy` is also installed.
gotchaWhen configuring proxying to *remote* hosts, simply setting `c.ServerApp.allow_remote_access = True` is insufficient. Jupyter Server Proxy uses its own `host_allowlist` configuration.fixUse `c.ServerProxy.host_allowlist = ['example.com', '192.168.1.1']` (or a similar list of allowed hosts) in your `jupyter_server_config.py`.
affects: All versions
gotchaIt is a significant security concern if processes started by Jupyter Server Proxy can be accessed directly, bypassing Jupyter's authentication and authorization mechanisms.fixAlways ensure that the proxied processes are only accessible through the Jupyter Server's proxy endpoint. A common strategy is to run Jupyter Server within a container and restrict network access to only the Jupyter Server itself.
affects: All versions
breakingCritical security vulnerabilities have been identified: Reflected XSS (CVE-2024-35225) due to unsanitized host parameter, and unauthenticated Websocket Proxying (CVE-2024-28179). These could allow an attacker to execute arbitrary JavaScript or bypass authentication for websocket connections.fixUpgrade to jupyter-server-proxy 4.5.0 or later immediately to patch these vulnerabilities.
affects: <4.5.0
Upgrade
Version history
4.5.0latest on PyPI · released Apr 1, 2026
Audit
Dependencies
jupyter_serverrequiredCore dependency as it's a Jupyter server extension. Implicitly required for versions >=4.0.0.
JupyterLaboptionalRequired for the bundled JupyterLab extension. JupyterLab >=3,<5 is supported.
JupyterHuboptionalRequired for the 'standalone' proxy feature.