JupyterLab Desktop

A desktop application for JupyterLab, based on Electron.

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

Download

Before installing please read the Python Environment Customization Guide if you plan to customize the Python environment to add new packages. If you have an existing JupyterLab Desktop installation, please uninstall it first by following 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 user's home is set as the root directory.
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.
If jlab command is used with a directory path as the argument then the directory in the argument is set as the root directory.

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

Configuration files

By default JupyterLab Desktop will only load and write to Jupyter configuration located in:

%APPDATA%\jupyterlab-desktop on Windows
$XDG_CONFIG_HOME/jupyterlab-desktop or ~/.config/jupyterlab-desktop on Linux
~/Library/jupyterlab-desktop on macOS

ignoring any other Jupyter configuration which may be present in standard Jupyter paths as defined by jupyter --paths. This includes jupyter-server settings, jupyterlab settings and workspaces, and any other configuration which would normally be shared between Jupyter installations. This is necessary to prevent a clash between the Desktop and any previous Jupyter installation.

You can change the configuration path by specifying JLAB_DESKTOP_CONFIG_DIR environment variable.

For instructions on how to copy the settings from previous JupyterLab installation please see the user guide.

Build dependencies

conda

You can install conda as part of a Miniforge installer.
(conda) Constructor to bundle JupyterLab Desktop Server into the stand-alone application. You can install Constructor using:
```
conda install -c conda-forge constructor
```
nodejs

You can install from https://nodejs.org/en/download/ or run:
```
conda install -c conda-forge nodejs
```
yarn

Install using
```
npm install --global yarn
```

Local development

JupyterLab Desktop bundles JupyterLab front-end and a conda environment as JupyterLab Desktop Server as its backend into an Electron application.

<platform>: mac, linux or win

Get the project source code

git clone https://github.com/jupyterlab/jupyterlab-desktop.git

Install dependencies and build JupyterLab Desktop
```
yarn
yarn build
```
Create the JupyterLab Desktop Server installer using
```
yarn create_env_installer:<platform>
```
Installer will be created in one of env_installer/JupyterLabDesktopAppServer<version>-MacOSX-x86_64.sh, env_installer/JupyterLabDesktopAppServer-<version>-Linux-x86_64.sh, env_installer/JupyterLabDesktopAppServer-<version>-Windows-x86_64.exe based on your platform
Now you can launch the JupyterLab Desktop locally using:
```
yarn start
```
If JupyterLab Desktop does not find a compatible Python environment configured, it will prompt for installation using JupyterLab Desktop Server installer or let you choose a custom environment on your computer at first launch.

Building for distribution

Build the application
```
yarn run clean && yarn build
```
Create JupyterLab Desktop Server installer
```
yarn create_env_installer:<platform>
```
Create JupyterLab Desktop installer which will also bundle JupyterLab Desktop Server installer.
```
yarn dist:<platform>
```
Application Installer will be created in dist/JupyterLab.dmg (macOS), dist/JupyterLab.deb (Debian, Ubuntu), dist/JupyterLab.rpm (Red Hat, Fedora) and dist/JupyterLab-Setup.exe (Windows) based on the platform

Release Instructions

For instructions on updating bundled JupyterLab packages and cutting a new release, please follow Release.md document.

benbenz/jupyterlab-econ-desktop