101.1. Use the JupyterLab#
101.1. Use the JupyterLab¶
For the Rubin Science Platform at data.lsst.cloud.
Data Release: Data Preview 1
Container Size: small
LSST Science Pipelines version: r29.2.0
Last verified to run: 2025-09-02
Repository: github.com/lsst/tutorial-notebooks
Learning objective: How to use the JupyterLab.
LSST data products: None.
Packages: None.
Credit: Originally developed by the Rubin Community Science team. Please consider acknowledging them if this notebook is used for the preparation of journal articles, software releases, or other notebooks.
Get Support: Everyone is encouraged to ask questions or raise issues in the Support Category of the Rubin Community Forum. Rubin staff will respond to all questions posted there.
1. Introduction¶
The Notebook Aspect of the Rubin Science Platform is JupyterLab, a browser-based software environment for programmatic data access and analysis.
This tutorial notebook does not import any python packages, execute any code, or access any data. It demonstrates only the basic functionality of the JupyterLab.
1.1. RSP documentation¶
See the Rubin Science Platform documentation site for information about user accounts, storage quotas, and the general capabilities of the RSP.
1.2. JupyterLab documentation¶
See the JupyterLab readthedocs site for more details about JupyterLab functionality.
2. Start a JupyterLab session¶
Go to data.lsst.cloud, select "Notebook Aspect", and follow the process to log in.
2.1. Server options¶
During log in, the server options must be selected, as shown in Figure 1.
Figure 1: Server options, with the recommended image (as of June 2025) selected and a Large server size.
2.1.1. Image¶
The image server option corresponds to the version of the software environment (the LSST Science Pipelines) that the JupyterLab session will use.
The recommended image has been selected by Rubin staff as a stable release, and Rubin documentation and tutorials are always kept up-to-date with the recommended image.
The recommended image is updated on timescales of weeks to months, so that changes are incremental and it is easier for everyone to evolve and maintain code and documentation.
Always choose the recommended image, unless you know you need an older or newer version of the LSST Science Pipelines (e.g., if you are re-running old custom code, or doing development work).
Old images are available in the drop-down menu, but are not kept indefinitely. It is recommended to update custom code to work with the latest recommended image.
2.1.2. Options¶
The options are the server size in terms of CPUs (central processing units) and RAM (random access memory, in gigabytes).
Use the following as a general guide.
Large: for retrieving and visualing data, running tutorial notebooks.
Small: for simply browsing or editing files and not accessing data.
Enable debug logs: do not check this box. The Debugger is not enabled at the Rubin Science Platform.
Reset user environment: check this box to clear software configuration files back to defaults (remove user-installed software).
2.2. Start the server¶
Click the orange bar in Figure 1 to start the server.
It can take a few minutes to create the server; longer if an old image was selected.
3. Main work area¶
The main work area, on the right in Figure 2, takes up most of the JupyterLab workspace and is where open files appear. The file browser, on the left in Figure 2, is discussed in the next section.
3.1. Welcome page¶
The welcome page will always display first and has a number of handy links.
The markdown file for this page is /notebooks/tutorials/welcome.md, and if it is accidentally deleted it is created automatically at login.
Figure 2: The welcome page, as of June 25 2025. This page will be updated with links to the latest data releases.
3.2. Launcher¶
The launcher is a tab in the main work area that appears by default after closing the welcome page.
Alternatively, open the launcher any time by clicking the blue + button at upper left.
Figure 3: JupyterLab with the launcher tab open in the main work area (as of June 25 2025).
Click on any panel to launch a new notebook, terminal, text or markdown file, python script, the help interface, or the Firefly image browser.
Opened files and applications will appear in the main work area in a new tab.
3.3. Tutorial notebooks¶
To open one of the Rubin tutorial notebooks, click on "Tutorials" in the top menu bar (seen in Figure 2) and select a tutorial from the drop-down menu.
A writeable version of the tutorial will open in the main work area, and be saved in the directory notebooks/tutorials/.
3.4. Side-by-side viewing¶
To open two applications side-by-side instead of as two tabs (top, Figure 4), click the rightmost tab and drag it down and to the right until the transparent blue box covers half the frame (middle, Figure 4), and let go. The two applications will be side-by-side (bottom, Figure 4).
Figure 4: How to view two applications side-by-side in the main work area.
4. File browser¶
The default view in the left sidebar is the file browser, as shown in Figure 2.
Click on the folder marked with the red arrow in Figure 5 to navigate back to the home directory.
Double-click on folders and files in the list to navigate the file system and to open files.
Opened files will appear in the main work area in a new tab.
Figure 5: A zoom-in on the file browser menu. Click on the little folder symbol marked with the red arrow to return to your home directory. Double-click on folders and files in the list to open them in the main work area.
5. Terminal¶
Use the launcher to open a terminal.
The terminal will open in the same directory as the file browser in the left sidebar.
Type ls and press the enter key to list the directory contents.
In the example shown in Figure 6, the terminal was launched while the file browser was in the /notebooks/tutorials folder.
Figure 6: The terminal interface.
5.1. Customize the prompt¶
In Figure 5, the command-line prompt is only the name of the directory, followed by the dollar sign $.
This change from the default was achieved by adding the following to the /.bashrc file:
# User specific aliases and functions
PS1='\W\$ '
5.2. Create a Rubin environment in a terminal¶
As each newly opened terminal suggests, to create a Rubin Observatory environment in a terminal session and access the Butler and the LSST Science Pipelines from the terminal command line, execute:
setup lsst_distrib
6. Switch to dark mode¶
Go to "Settings", then "Theme", and then "JupyterLab Dark".
Figure 7: How to switch to dark mode.
7. Shut down the server¶
It is recommended to always save and close all files, and choose "File" and then "Save all, exit, and log out" at the end of every session.
This is important to preserve resources for other users and to ensure re-entry to the RSP in a known state every time.
To help users avoid issues with stale instances, sessions will be automatically shut-down after 5 days of inactivity, or after 25 days.