What Is a Workspace?

The Basics

Jupyter Workspaces are collections of files, notebooks, and other related resources that can be run using a Jupyter Notebook or JupyterLab.

You can launch a Jupyter Workspace from Spell's web console, or from the CLI. For more on how to install the CLI, go to our Quickstart docs.

Creating a Workspace in the Web

Workspaces are created using the Create New Workspace button at the top right of the Workspaces section of the web console.

This will launch the Create Workspace wizard, which will take you through the steps to add code and resources to your Notebook server environment.

1: Name and Code

First, you'll be asked to give your Workspace a name (required). You'll also have the option to add code by initializing your Workspace from a GitHub repository. If you enter a URL for a public GitHub Repo, your Workspace environment will be initialized with all the files and notebooks associated with that repo.

In the below screenshot, we are intitializing our Workspace with a style transfer repository.

A screenshot of the first screen in the create new workspace wizard

2: Environment

Next, you'll set your environment settings. This includes choosing a machine type (a full list of machine types is available on our pricing page), a framework, Jupyter Lab/Notebook, and adding any optional dependencies such as pip or apt packages.

Since the code running inside this Workspace doesn't need other dependencies, we don't need to add additional pip and apt dependencies beyond what's included in the Spell default environment.

A screenshot of the second screen in the create new workspace wizard

3: Datasets

Adding datasets is optional. While you can add datasets by including them in a GitHub repo and adding that in step 1, it is better to upload the datasets to Spell and mount them into your Workspace. This way multiple Workspaces can quickly access the same dataset without having to upload it to Spell more than once. This is especially useful for teams where multiple people are using the same dataset for their work.

For this example, we will add two image datasets from our uploads folder. (For more on how to upload files, see our uploads docs). To do this, we specify the path to our file; we've also chosen to rename our mounted directories using the :<new_name> format.

A screenshot of the third screen in the create new workspace wizard

4: Confirm Variables

The final screen in the wizard asks you to confirm your settings. You'll be able to change most of these settings later by editing your Workspace.

A screenshot of the final screen, a receipt of the selections from past screens, in the create new workspace wizard

Creating a Workspace in the CLI

You can also create a workspace and launch a notebook server from the CLI using the spell jupyter command.

The spell jupyter command works similarly to spell run, taking many of the same parameters such as --machine-type, --framework, and --pip. Additionally, you can specify if you want to launch Jupyter lab with --lab (the default is Jupyter Notebook). To read more about the command and its parameters, go to our CLI reference docs.

If the command is run from within a Git repository, any code and files committed to that repo will show up in the Jupyter workspace.

The only required argument is a workspace name. Below is an example of a spell jupyter command:

$ spell jupyter -t K80 --framework tensorflow --pip joblib -m myFile myNewWorkspace

The command will automatically launch a notebook server.

The Notebook Server

The Notebook Server contains your Jupyter Notebook or JupyterLab workspace, and the Spell header where you can stop your notebook. As you can see, the files and directories we added in the Creating a Workspace in the CLI step are all included in our JupyterLabs file system.

A screenshot of the Jupyter Notebook Server

Editing a Notebook

You can only edit a stopped workspace. You can stop your workspace using the stop button to the top right of your Notebook Server, or by using the actions button on the workspaces list page (see screenshot below).

The Edit Workspace page allows you to add or remove dependencies, mount files, and change the machine type, framework, and name of your Workspace. The only selection from the Create Workspace flow that you are not able to change is how your Workspace was initialized (empty or with code from a GitHub repository).

A screenshot of the workspace list page with the action menu opened and edit workspace selected

Collaborating on a Workspace

Team members can view, edit, and restart each other's stopped workspaces.


Only one person is allowed to run a notebook server in a workspace at a time. A notebook server must be stopped before another person can edit the workspace or restart the notebook server.