jupyterlab-desktop

Installation | User guide | Contributing | Getting help

JupyterLab Desktop

JupyterLab Desktop is the cross-platform desktop application for JupyterLab. It is the quickest and easiest way to get started with Jupyter notebooks on your personal computer, with the flexibility for advanced use cases.

Installation

Install JupyterLab Desktop using one of the methods listed below for your system.

Windows (10, 11) Mac (macOS 12+) Linux (Ubuntu 18.04+, Fedora 32+, Debian 10+) x64 Installer arm64 Installer (Apple silicon) Snap Store [recommended] x64 Installer (Intel chip) .deb x64 Installer (Debian, Ubuntu) .rpm x64 Installer (Red Hat, Fedora, SUSE)

Additionally, JupyterLab Desktop can be installed on Windows via winget: winget install jupyterlab.

If you need to remove a previous JupyterLab Desktop installation, please follow the uninstall instructions.

Launching JupyterLab Desktop

JupyterLab Desktop can be launched from the GUI of your operating system by clicking the application's icon or by using jlab command from the command line. Double clicking .ipynb files is also supported and it will launch JupyterLab Desktop and load the notebook file.

JupyterLab Desktop sets File Browser's root directory based on the launch method.

• If launched from the application icon on GUI or by using jlab command without any arguments, then the default working directory is set as the root directory. The default working directory is user home directory but it can be customized from the Settings dialog.
• If launched by double clicking .ipynb file or jlab command with a file path as the argument, then file's parent directory is set as the root directory. Similarly, if a file is opened using the Open... or Open File... links in the Start section or by using drag & drop, then file's parent directory is set as the root directory.
• If jlab command is used with a directory path as the argument or with the --working-dir argument then the directory in the argument is set as the root directory. Similarly, if a folder is opened using the Open Folder... link in the Start section or by using drag & drop, then the opened directory is set as the root directory

Sessions and Projects

Sessions represent local project launches and connections to existing JupyterLab servers. Each JupyterLab UI window in the app is associated with a separate session and sessions can be restored with the same configuration later on.

Each launch of JupyterLab in a different working directory is a separate project and projects can have their own configuration such as Python environment and UI layout.

Session start options

You can start a new session by using the links at the Start section of the Welcome Page.

• New notebook... creates a new notebook in the default working directory.
• New session... launches a new JupyterLab session in the default working directory.
• Open... starts a new JupyterLab session in the selected working directory. If files are chosen, selected files' parent directory becomes the working directory and selected files are opened in the session. On Windows and Linux Open Folder... and Open Files... options are presented as separate items.
• Connect... creates a session by connecting to an existing JupyterLab server running locally or remotely. Locally running JupyterLab servers are automatically detected and listed in the Connect dialog.

Similarly, CLI launches of the application, dropping files and folders, and double clicking to open files create new sessions as well.

Previously opened sessions are stored as part of application data and they are listed on Welcome Page. Clicking an item in the Recent sessions list restores the selected session.

jlab command-line launch examples

• Open directories using relative or absolute path
  • jlab . launch in current directory
  • jlab ../notebooks launch with relative path
  • jlab /Users/username/notebooks launch with absolute path
• Open notebooks and other files using relative or absolute path
  • jlab /Users/username/notebooks/test.ipynb launch notebook with absolute path
  • jlab ../notebooks/test.ipynb launch notebook with relative path
  • jlab ../test.py launch python file with relative path
• Open with a custom Python environment
  • jlab --python-path /Users/username/custom_env/bin/python ../notebooks/test.ipynb launch notebook with custom Python environment
• Connect to existing JupyterLab server
  • jlab https://example.org/lab?token=abcde

See CLI documentation for more CLI commands and options.

JupyterLab Extension support

JupyterLab Desktop currently supports user-friendly prebuilt extensions. Source extensions which require rebuilding are not supported.

Guides and Help

• See user guide for configuration options

• Python environment management guide for managing Python environments on your system using JupyterLab Desktop

• See CLI documentation for CLI commands and options

• See troubleshooting guide for troubleshooting issues

Contributing

See CONTRIBUTING.md for building, running, testing and packaging the application.

Getting help

Questions about using JupyterLab Desktop are welcome on the Jupyter Discourse forum. If you have found a defect, check the troubleshooting guide first, then open an issue.

Security vulnerabilities never go to a public issue: the Jupyter security policy asks for a GitHub Security Advisory on this repository, and [email protected] only when that is not possible.