DataSpell 2022.2 Help

Manage Jupyter notebook servers

In DataSpell, you can execute code cells using:

  • Managed server – a Jupyter server that is automatically launched by DataSpell for the current project. It will be terminated when you close DataSpell.

  • Configured server – any Jupyter server that you connect to by specifying its URL and token.

Launch a local Jupyter server

  • To run a Jupyter server just execute any code cell. When you initiate cell execution, DataSpell launches the Jupyter server on the local host using any available port (by default, it is the 8888 port). You can switch to the Jupyter Server tool window to preview server's configuration details.

Jupyter server is running. Jupyter tool window

Once the server is launched, it is shown as a managed server in the list of the servers in the Jupyter toolbar. You can also see the automatically created server kernel in the list of kernels. This kernel is based on the .

Jupyter notebook toolbar; Managed server is connected

Connect to a Jupyter server

  1. Click the Add connection icon on the toolbar of the Workspace tool window to establish a connection to a Jupyter server.

  2. In the New Jupyter Connection dialog, select the connection type:

    • Run local Jupyter server: run a Jupyter server in a local directory that will be attached to your workspace.

    • Connect to running Jupyter server: establish a connection to any locally run Jupyter server. The option is enabled if there is at least one active Jupyter server on your machine. Run jupyter notebook list in the Terminal window to check if there are any.

    • Connect by URL: establish a connection to a remote Jupyter server. The target URL should contain a server name or its address, and the access token.

    Add a remote connection to a Jupyter server
    Once the connection has been established, the server and its structure are shown in the Workspace tool window.
    Remote Jupyter server in the Workspace tool window

Connect to a Jupyter server using OAuth authentication

You can establish connection to a Jupyter server through OAuth authentication using the JupyterHub API token.

  1. Click the Add connection icon on the toolbar of the Workspace tool window.

  2. Select Connect by URL and enter the target Jupyter server address in the Server URL field.

    Connecting to a JupyterHub server

    Click the Link to the token page link.

  3. You will be prompted to login into GitHub. Click Sign in with GitHub.

    GitHub authentication

    Note that although GitHub is used in this example, it is just one of the supported OAuth providers (see the complete list in JupyterHub documentation).

  4. Confirm your authorization on GitHub or provide your credentials.

    Confirming GitHib authorization
  5. The token page should open in the browser. Click the Request new API token button and copy the token that appears in the You new API token area.

    Requesting a new API token
  6. Paste the value into the Token field of the Authenticating to JupyterHub dialog. Also, specify the system username that will be used to run a notebook process.

    Providing a token and a username

    Click OK and then Add to complete the task.

Stop the Jupyter server

  • To stop any running server, switch to the Jupyter Server tool window and click the the Stop button icon. Preview the status in the Server Log window.

Stopping the server

Once you have shut down the server, the current session is terminated. When you start the server next time using the Run server icon icon, execution results for all previous sessions and all notebooks will be lost.

Restart the kernel

  • You might want to refresh your calculations without shutting down the entire server and affecting any other notebooks. To restart the currently running kernel, click Kernels on the Jupyter notebook toolbar and preview the status in the Server Log window.

    Restarting the current kernel

    You can find other kernel specific commands in the Kernel menu of the DataSpell main menu.

You can execute your notebook code cells on a specific Jupyter server.

Configure the Jupyter server

When you launch any managed server, by default it uses the current and the automatically selected port. However, you can select any other available in your DataSpell instance and specify an alternative port. You can also connect to any configured server if you know its URL and token.

  1. To open the server settings, select Configure Jupyter Server in the list of the Jupyter servers.

    Configure a Jupyter server

  2. Configure the server options:

    • To customize the default Jupyter server, in the Jupyter Server dialog, select Managed Server and from the Python interpreter list select any local Python .

      Select an interpreter for the managed server
    • To change the automatically detected port, type its number in the Port field.

      Specifying the port number for the managed server
    • To connect to any running Jupyter server, in the Jupyter Server dialog, select Configured Server and specify server's path including an URL and a token.

      Configure a Jupyter server. Settings dialog

  3. Once done with configuring, click Apply and OK.

  4. Execute any code cell to run the managed server or to connect to the running configured server.

  5. If you see the following warning, the kernel of the newly configured server doesn't match your current Python interpreter. For example, it might have a different set of the installed packages.

    Warning requesting to register interpreter as a kernel

    You can register your Python interpreter as a kernel on the configured server by clicking the corresponding link. After that you can see it in the list of the kernels for the configured server.

    Two kernels are registered for the configured server
Last modified: 06 September 2022