Jupyter Server Terminals

0.5.4 verified Tue May 12 auth: no python install: stale

Jupyter Server Terminals is a Jupyter Server Extension that provides robust terminal support within the Jupyter environment. It allows users to run system shells directly in their web browser, offering functionalities akin to a local terminal. The library is actively maintained, with regular releases focusing on bug fixes and maintenance, and is currently at version 0.5.4. It requires Python >=3.8.

pip install jupyter_server_terminals

Common errors

error RuntimeError: Jupyter Server Terminals requires Jupyter Server 2.0+ ↓

cause This error occurs when `jupyter-server-terminals` is installed with an older version of `jupyter-server` that does not meet the minimum requirement of 2.0+.

fix

Upgrade your jupyter-server installation to version 2.0 or newer using pip install --upgrade jupyter-server or conda update jupyter-server.

error Disabling terminals plugin because they are not available on the server. ↓

cause This message, often seen in the browser console, indicates that the Jupyter server-side component for terminals is either not installed, not enabled, or its configuration cannot be found, preventing the client from utilizing terminal functionality.

fix

Ensure jupyter-server-terminals is installed and enabled. Run pip install jupyter-server-terminals (or conda install jupyter-server-terminals -c conda-forge) and then jupyter server extension enable jupyter_server_terminals.

error 500 Internal Server Error ↓

cause A '500 Internal Server Error' when interacting with terminals often points to a broader issue with the Jupyter server environment, possibly due to corrupted installations, dependency conflicts (e.g., `tornado` version mismatches), or misconfigurations preventing the server from handling requests correctly.

fix

Try reinstalling jupyter-server and jupyter-server-terminals in a clean virtual environment: pip uninstall jupyter-server jupyter-server-terminals && pip install jupyter-server jupyter-server-terminals. Also, ensure all Jupyter-related packages are up-to-date and compatible.

error WebSocket connection failed ↓

cause This error signifies a failure in the real-time communication channel between the client (browser) and the Jupyter server, which is essential for interactive terminals, often due to network issues, proxy misconfigurations, or an improperly running Jupyter server.

fix

Check for network connectivity issues, verify any proxy configurations (especially in a JupyterHub environment), and ensure the Jupyter server is running without errors in its logs. Sometimes restarting the Jupyter server can resolve transient connection problems.

Warnings

breaking Jupyter Server Terminals versions 0.5.0 and newer explicitly require Jupyter Server 2.0+ to function correctly. Older versions of Jupyter Server will result in an error during extension loading. ↓

fix Upgrade your `jupyter-server` installation to version 2.0 or higher: `pip install --upgrade jupyter-server`.

gotcha The 'Terminals Service' transitioned from a core Jupyter Service to a Jupyter Server extension in Jupyter Server 2.0. While most end-users won't notice, this impacts how the service is managed and can be optionally disabled, which is relevant for sensitive deployment environments or advanced configurations. ↓

fix Be aware of this architectural change if you're developing extensions that interact directly with Jupyter Server services or managing custom deployments. The service can now be managed as a standard Jupyter extension.

gotcha Jupyter environments (including terminals) can suffer from memory issues, leading to unresponsive sessions or saving errors. This is often due to poor 'server hygiene,' such as not closing notebooks/terminals, excessive output, or inefficient code. ↓

fix Always close and halt notebooks (`File > Close and Halt`) and exit terminals (`exit` command) when not in use. Minimize the number of open tabs and avoid printing excessively large outputs. Re-use variables instead of creating multiple copies of large data in memory.

gotcha On *nix shells in JupyterLab, the default keyboard shortcut for copying (Ctrl+Shift+C) can conflict with the default shortcut for toggling the command palette (`apputils:activate-command-palette`). ↓

fix If experiencing conflicts, consider changing the keyboard shortcut for either copy or the command palette in JupyterLab's settings. Alternatively, use Ctrl+Shift+V for paste, which works as usual, or hold Shift and right-click for the native browser context menu (though this may not work in all browsers).

breaking The test script failed with a `SyntaxError` because `pip install` was used as a Python statement. `pip install` is a shell command and cannot be run directly as Python code within a script. This prevents the library from being installed and evaluated. ↓

fix Execute `pip install` commands in a shell environment (e.g., command line, shell script, or via `subprocess` in Python), not as direct Python code within a `.py` file.

breaking The test or installation script attempted to execute a shell command (e.g., `pip install`) directly within a Python script, leading to a `SyntaxError`. This prevents the specified libraries from being installed and the rest of the script from running. ↓

fix Ensure shell commands are run in a shell environment (e.g., your terminal) or use Python's `subprocess` module to execute them programmatically from within a script. For package installation, run `pip install <package_names>` in your command line interface before executing your Python script.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 21.5M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.9s - 22M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 24.3M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 2.0s - 25M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 15.9M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.8s - 16M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 15.7M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.8s - 16M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 21.0M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 2.2s - 21M

3.9 slim (glibc) - - - -

Imports

Extension configuration
```
This library is primarily a Jupyter Server extension. Direct Python imports for programmatic end-user terminal creation or management are not its primary interface. Its functionality is exposed via the Jupyter Server and its web UI (JupyterLab/Notebook).
```
Users typically interact with terminals via the Jupyter web interface after installing the extension. For advanced server-side configuration, one would interact with the Jupyter Server's extension management system, not direct imports from jupyter_server_terminals.

Quickstart last tested: 2026-04-24

Install the `jupyter_server_terminals` extension along with `jupyterlab` (or `notebook`). Once installed, start JupyterLab from your terminal. The terminal functionality will be automatically available within the JupyterLab interface. You can open a new terminal from the Launcher or through the File menu.

pip install jupyter_server_terminals jupyterlab
jupyter lab