Usage#

jupyter_app_launcher relies on YAML files to create and add entries to the launcher. Depending on the type of entry, different parameters are required.

Configuration file location#

By default, jupyter_app_launcher will look for jupyter_app_launcher directory in the list of data directories of Jupyter (i.e. the data section of the jupyter --path command), for example:

> jupyter --path

config:
    /home/***/mambaforge/envs/appdev/etc/jupyter
    /home/***/.jupyter
    /home/***/.local/etc/jupyter
    /usr/local/etc/jupyter
    /etc/jupyter
data: # -> Here are the paths used by jupyter_app_launcher
    /home/***/mambaforge/envs/appdev/share/jupyter
    /home/***/.local/share/jupyter
    /usr/local/share/jupyter
    /usr/share/jupyter
runtime:
    /home/***/.local/share/jupyter/runtime

If under the jupyter_app_launcher directory of these paths, YAML files (.yaml, .yml) with name starting with jp_app_launcher exist, they will be used. For example, the following files will be loaded:

/home/***/mambaforge/envs/appdev/share/jupyter/jupyter_app_launcher/jp_app_launcher.yaml
/home/***/mambaforge/envs/appdev/share/jupyter/jupyter_app_launcher/jp_app_launcher_my_app.yml
/home/***/.local/share/jupyter/jupyter_app_launcher/jp_app_launcher_my_other_app.yml

In addition to this behavior, jupyter_app_launcher also loads the YAML files with names starting with jp_app_launcher in the directory where JupyterLab was started, and also in the path defined by the JUPYTER_APP_LAUNCHER_PATH environment variable.

Note

This extension only reads the configuration file when JupyterLab starts. Users need to restart JupyterLab after changing the config file.

Configuration file content#

The YAML file should contain an array of objects, jupyter_app_launcher will create the corresponding launcher entry for each object. Here is an example of the configuration file:

- title: Dashboard example
  description: Example of opening a notebook in dashboard mode without Voila
  source: ../../samples/sample.ipynb
  cwd: ../../samples
  type: notebook-grid

- title: Notebook example
  description: Example of opening a notebook in dashboard mode without Voila
  source: ../../samples/sample.ipynb
  cwd: ../../samples
  type: notebook
  catalog: Another catalog

- title: Voila example
  description: Example of opening a notebook in dashboard mode with Voila
  source: ../../samples/sample.ipynb
  cwd: ../../samples
  type: notebook-voila
  args:
      theme: dark
  catalog: Another catalog

- title: URL example
  description: Example of opening a URL in a tab
  source: https://jupyterlab.readthedocs.io/en/stable/
  type: url
  catalog: Another catalog
  args:
      sandbox: [ 'allow-same-origin', 'allow-scripts', 'allow-downloads', 'allow-modals', 'allow-popups']

- title: URL example (new window)
  description: Example of opening a URL in a new browser window
  source: https://jupyterlab.readthedocs.io/en/stable/
  type: url
  catalog: Another catalog
  args:
      createNewWindow: true

- title: Streamlit example
  description: Example of opening a streamlit app
  source: http://localhost:$PORT/
  cwd: ./
  type: local-server
  args:
    - streamlit
    - run
    - st_app.py
    - --server.headless=true
    - --server.port=$PORT
  catalog: Another catalog

- title: Command example
  description: Example of calling JupyterLab commands
  type: jupyterlab-commands
  source:
    - label: Command 1
      id: 'filebrowser:open-path'
      args:
        path: sample.ipynb
    - label: Command 2
      id: 'filebrowser:open-path'
      args:
        path: sample-2.ipynb
  catalog: Another catalog

The common fields of the configurations are: title, description icon and catalog.

  • title: Title of the launcher entry.

  • description (Optional): Description of the launcher entry. It will be shown on mouse hover.

  • icon (Optional): Path to the icon of the launcher entry. If it is not defined, the initials of the title will be used as the icon.

  • catalog (Optional): Catalog of the launcher entry, entry with the same catalog will be grouped in the same group in the launcher, If it is not defined, Jupyter App catalog will be used.

Other fields will have different meanings depending on the entry type. In this section, we will detail these fields for each type of entry.

Open a predefined notebook#

This launcher entry will create a new notebook in the current working directory of JupyterLab with predefined content.

- title: Notebook example
  description: Example of opening a notebook in dashboard mode without Voila
  type: notebook
  source: ../../samples/sample.ipynb
  cwd: ../../samples
  args:
    widget-type: 'default'
  catalog: Notebook catalog

  • type = notebook

  • source: Path to the notebook (can be stored anywhere) which will be copied to the current working directory of JupyterLab. It can be an absolute path or a relative path to the directory of the configuration file.

  • args (Optional): By default the notebook will be opened with the default notebook view. Users can customize the document widget to open the notebook by setting the widget-type argument. For example, to open the notebook with the Voila preview widget, set widget-type to Voila Preview.

  • cwd: Unused.

_images/notebook.gif

Notebook demo.#

Open a predefined markdown file#

This launcher entry will render the content of a predefined markdown file.

- title: Markdown example
  description: Example of opening a Markdown file in a tab
  source: ../../samples/sample.md
  type: markdown
  catalog: Another catalog

  • type = markdown

  • source: Path to the markdown file. It can be an absolute path or a relative path to the directory of the configuration file.

  • cwd: Unused.

_images/markdown.gif

Markdown demo.#

Render a notebook in gridstack dashboard mode#

This launcher entry will open a predefined notebook in the gridstack dashboard view. Users need to use the jupyterlab-gridstack extension to edit the layout of the dashboard and save the dashboard metadata. The launcher entry will read the metadata and then render the notebook with the saved layout.

- title: Dashboard example
  description: Example of opening a notebook in dashboard mode without Voila
  source: ../../samples/sample.ipynb
  cwd: ../../samples
  type: notebook-grid

  • type = notebook-grid

  • source: Path to the notebook file. It can be stored anywhere on your system and can be an absolute path or a relative path to the directory of the configuration file.

  • cwd: The working directory where the notebook will be started. it’s important to set this field correctly if you need to load local files with relative paths in your notebook.

_images/notebook-grid.gif

Notebook dashboard demo.#

Note

  • This dashboard mode does not depend on Voila. It’s a frontend-only approach and is a lightweight solution for dashboarding notebooks.

  • Users can also open a notebook in this dashboard mode by right clicking on the notebook and select Open With -> Notebook GridStack in the context menu.

Open a notebook with Voila#

This launcher entry also renders the predefined notebook in dashboard mode but unlike notebook-grid, this mode uses Voila and users have access to all configurations of Voila, for example, the template or themes.

- title: Voila example
  description: Example of opening a notebook in dashboard mode with Voila
  source: ../../samples/sample.ipynb
  cwd: ../../samples
  type: notebook-voila
  args:
      theme: dark
      template: gridstack

  catalog: Another catalog

  • type = notebook-voila

  • source: Path to the notebook file. It can be stored anywhere on your system and can be an absolute path or a relative path to the directory of the configuration file.

  • cwd: Unused, Voila will be started in the same directory of the source notebook.

  • args: The arguments list that will be passed to the Voila startup command. For example, in the code block above, --theme=dark and --template=gridstack will be passed to the Voila command.

_images/voila.gif

Voila demo.#

Start a local process and open the predefined URL.#

This launcher entry will start a process with predefined commands and open a local URL in a new panel of JupyterLab.

- title: Streamlit example
  description: Example of opening a streamlit app
  source: http://localhost:$PORT/
  cwd: ./
  type: local-server
  args:
    - streamlit
    - run
    - st_app.py
    - --server.headless=true
    - --server.port=$PORT
  catalog: Another catalog

  • type = local-server

  • args: The command which will be executed inside a sub-process, defined as a list of arguments. For the web server applications that need to define the listening port, users can use the PORT variable.

  • source: The URL which will be opened after executing the command. jupyter_app_launcher will poll for the availability of the URL for 120 seconds. Environment variables inside URL will be substituted with the value of the variable.

  • cwd: Current working directory of the subprocess.

_images/local-url.gif

Local server demo.#

Note

jupyter_app_launcher uses the jupyter-server-proxy extension to expose the local URL, so using this entry type behind a reserve proxy server is straightforward.

Open a remote URL.#

This launcher entry will open the predefined URL in a new panel of JupyterLab by using an IFrame element.

- title: URL example
  description: Example of opening a URL in a tab
  source: https://jupyterlab.readthedocs.io/en/stable/
  type: url
  catalog: Another catalog
  args:
      sandbox: [ 'allow-same-origin', 'allow-scripts', 'allow-downloads', 'allow-modals', 'allow-popups']
      referrerPolicy: ['no-referrer']
      createNewWindow: false

  • type = url

  • source: The URL which will be opened by this entry.

  • args (Optional): The sandbox and referrer policy setting of the IFrame. Alternatively, set createNewWindow to true to open the URL in a new browser window.

  • cwd: Unused.

_images/url.gif

URL demo.#

Run JupyterLab commands.#

This launcher entry will run predefined JupyterLab commands.

- title: Command example 2
  description: Example of calling JupyterLab commands
  type: jupyterlab-commands
  source:
    - label: Command 1
      id: 'filebrowser:open-path'
      args:
        path: sample.ipynb
    - label: Command 2
      id: 'another-jupyterlab-command-id'
      args: my-args
  catalog: Config 2

  • type = jupyterlab-commands

  • source: The list of JupyterLab commands to be called. Each command is defined by 3 property:

    • label: The user-defined label of the command.

    • id: The id of the JupyterLab command.

    • args: The arguments to be passed “as-is” to the command.

  • args: Unused.

  • cwd: Unused.

The execution of commands will be stopped if a command fails, and the error message will be shown in a dialog.

Open JupyterLab terminal.#

This launcher entry will open JupyterLab terminal and execute the defined command.

- title: Terminal example
  description: Example of opening JupyterLab terminal
  type: terminal
  source: 'ls -l'
  cwd: '../'
  args:
    reuse: true
  catalog: Config 2

  • type = terminal

  • source: the command to be executed at startup

  • cwd: The CWD of the terminal. It can be an absolute path or a relative path to the CWD of JupyterLab.

  • args (Optional): By default the terminal session will be created independently, set reuse to true to use the same terminal session.

Running subprocesses manager#

In the case of notebook-voila or local-server launcher entry, jupyter_app_launcher will start the corresponding process in a subprocess. Users can keep track and shut down running subprocesses by using the Launcher Application section in the running panel of JupyterLab

_images/running.png

Running subprocess#

Using jupyter_app_launcher with JupyterLite#

jupyter_app_launcher is compatible with JupyterLite, but due to the limit of the lite kernel, the entry types using subprocess do not work in JupyterLite. The available entry types in JupyterLite are: notebook, notebook-grid, markdown, and url. To use jupyter_app_launcher, users need to add the extension and the configuration file to the deployment.

  • To add jupyter_app_launcher extension to a JupyterLite website, users can refer to the official documentation here.

  • To add the configuration to JupyterLite, jupyter_app_launcher provides the command app_launcher to do the process:

    jupyter app_launcher build <path-containing-the-YAML-file> <path-to-the -JupyterLite-directory>

The above command will read the config.yaml file in the first path argument and put it in the overrides.json file (the command will create it if needed) of the JupyterLite deployment in the second path argument. Users need to rebuild the deployment to take the changes.

Using jupyter_app_launcher on myBinder#

Users can refer to the example on project repository for deploying jupyter_app_launcher on myBinder.

On this page
Show Source