Like the classic notebook, JupyterLab provides a way for users to copy URLs that open a specific notebook or file. Additionally, JupyterLab URLs are an advanced part of the user interface that allows for managing workspaces. These two functions -- file paths and workspaces -- can be :ref:`combined in URLs that open a specific file in a specific workspace <url-combine>`.
JupyterLab's file navigation URLs adopts
the nomenclature of the classic notebook; these URLs are /tree
URLs:
http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb
Entering this URL will open the notebook in JupyterLab in :ref:`single-document mode <tabs>`.
JupyterLab sessions always reside in a workspace. Workspaces contain the state of JupyterLab: the files that are currently open, the layout of the application areas and tabs, etc. When the page is refreshed, the workspace is restored.
The default workspace does not have a name and resides at the primary /lab
URL:
http(s)://<server:port>/<lab-location>/lab
All other workspaces have a name that is part of the URL:
http(s)://<server:port>/<lab-location>/lab/workspaces/foo
Workspaces save their state on the server and can be shared between multiple users (or browsers) as long as they have access to the same server.
A workspace should only be open in a single browser tab at a time. If JupyterLab detects that a workspace is being opened multiple times simultaneously, it will prompt for a new workspace name. Opening a document in two different browser tabs simultaneously is also not supported.
You can copy the contents of a workspace into another workspace with the clone
url parameter.
To copy the contents of the workspace foo
into the workspace bar
:
http(s)://<server:port>/<lab-location>/lab/workspaces/bar?clone=foo
To copy the contents of the default workspace into the workspace foo
:
http(s)://<server:port>/<lab-location>/lab/workspaces/foo?clone
To copy the contents of the workspace foo
into the default workspace:
http(s)://<server:port>/<lab-location>/lab?clone=foo
Use the reset
url parameter to clear a workspace of its contents.
To reset the contents of the workspace foo
:
http(s)://<server:port>/<lab-location>/lab/workspaces/foo?reset
To reset the contents of the default workspace:
http(s)://<server:port>/<lab-location>/lab/workspaces/lab?reset
These URL functions can be used separately, as above, or in combination.
To reset the workspace foo
and load a specific notebook afterward:
http(s)://<server:port>/<lab-location>/lab/workspaces/foo/tree/path/to/notebook.ipynb?reset
To clone the contents of the workspace bar
into the workspace foo
and
load a notebook afterward:
http(s)://<server:port>/<lab-location>/lab/workspaces/foo/tree/path/to/notebook.ipynb?clone=bar
To reset the contents of the default workspace and load a notebook:
http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb?reset
JupyterLab provides a command-line interface for workspace import
and
export
:
$ # Exports the default JupyterLab workspace
$ jupyter lab workspaces export
{"data": {}, "metadata": {"id": "/lab"}}
$
$ # Exports the workspaces named `foo`
$ jupyter lab workspaces export foo
{"data": {}, "metadata": {"id": "/lab/workspaces/foo"}}
$
$ # Exports the workspace named `foo` into a file called `file_name.json`
$ jupyter lab workspaces export foo > file_name.json
$
$ # Imports the workspace file `file_name.json`.
$ jupyter lab workspaces import file_name.json
Saved workspace: <workspaces-directory>/labworkspacesfoo-54d5.jupyterlab-workspace
The export
functionality is as friendly as possible: if a workspace does not
exist, it will still generate an empty workspace for export.
The import
functionality validates the structure of the workspace file and
validates the id
field in the workspace metadata
to make sure its URL is
compatible with either the workspaces_url
configuration or the page_url
configuration to verify that it is a correctly named workspace or it is the
default workspace.