jupyterlab/docs/source/user/interface.rst

.. _interface:

The JupyterLab Interface
------------------------

JupyterLab provides flexible building blocks for interactive,
exploratory computing. While JupyterLab has many features found in
traditional integrated development environments (IDEs), it remains
focused on interactive, exploratory computing.

The JupyterLab interface consists of a :ref:`main work area <main-area>`
containing tabs of documents and activities, a collapsible :ref:`left sidebar
<left-sidebar>`, and a :ref:`menu bar <menu-bar>`. The left sidebar contains a
:ref:`file browser <working-with-files>`, the :ref:`list of running kernels and
terminals <running>`, the :ref:`command palette <commands>`, the :ref:`notebook
cell tools inspector <notebook>`, and the :ref:`tabs list <tabs>`.

.. image:: images/interface_jupyterlab.png
   :align: center
   :class: jp-screenshot

.. _menu-bar:

Menu Bar
~~~~~~~~

The menu bar at the top of JupyterLab has top-level menus that expose
actions available in JupyterLab with their keyboard shortcuts. The
default menus are:

-  **File**: actions related to files and directories
-  **Edit**: actions related to editing documents and other activities
-  **View**: actions that alter the appearance of JupyterLab
-  **Run**: actions for running code in different activities such as
   notebooks and code consoles
-  **Kernel**: actions for managing kernels, which are separate processes
   for running code
-  **Tabs**: a list of the open documents and activities in the dock panel
-  **Settings**: common settings and an advanced settings editor
-  **Help**: a list of JupyterLab and kernel help links

:ref:`JupyterLab extensions <user_extensions>` can also create new top-level menus in the menu
bar.

.. _left-sidebar:

Left Sidebar
~~~~~~~~~~~~

The left sidebar contains a number of commonly-used tabs, such as a file
browser, a list of running kernels and terminals, the command palette,
and a list of tabs in the main work area:

.. image:: images/interface_left.png
   :align: center
   :class: jp-screenshot

.. _left-sidebar-toggle:

The left sidebar can be collapsed or expanded by selecting "Show Left Sidebar"
in the View menu or by clicking on the active sidebar tab:


.. raw:: html

  <div class="jp-youtube-video">
     <iframe src="https://www.youtube-nocookie.com/embed/PlJGecfetek?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  </div>

JupyterLab extensions can add additional panels to the left sidebar.

.. _main-area:

Main Work Area
~~~~~~~~~~~~~~

.. _main-area-vid:

The main work area in JupyterLab enables you to arrange documents (notebooks,
text files, etc.) and other activities (terminals, code consoles, etc.) into
panels of tabs that can be resized or subdivided. Drag a tab to the center of a
tab panel to move the tab to the panel. Subdivide a tab panel by dragging a tab to
the left, right, top, or bottom of the panel:

.. raw:: html

  <div class="jp-youtube-video">
    <iframe src="https://www.youtube-nocookie.com/embed/Ka8qS7CO1XQ?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  </div>

The work area has a single current activity. The tab for the current activity is
marked with a colored top border (blue by default).

.. _tabs:

Tabs and Single-Document Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Tabs panel in the left sidebar lists the open documents or
activities in the main work area:

.. image:: images/interface_tabs.png
   :align: center
   :class: jp-screenshot

The same information is also available in the Tabs menu:

.. image:: images/interface_tabs_menu.png
   :align: center
   :class: jp-screenshot

.. _tabs-singledocument:

It is often useful to focus on a single document or activity without closing
other tabs in the main work area. Single-document mode enable this, while making
it simple to return to your multi-activity layout in the main work area.
Toggle single-document mode using the View menu:

.. raw:: html

  <div class="jp-youtube-video">
    <iframe src="https://www.youtube-nocookie.com/embed/DO7NOenMQC0?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  </div>

When you leave single-document mode, the original layout of the main
area is restored.

Context Menus
~~~~~~~~~~~~~

.. _context-menus-rightclick:

Many parts of JupyterLab, such as notebooks, text files, code consoles,
and tabs, have context menus that can be accessed by right-clicking on
the element:

.. raw:: html

  <div class="jp-youtube-video">
    <iframe src="https://www.youtube-nocookie.com/embed/y30fs6kg6fc?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  </div>

.. _context-menus-shiftrightclick:

The browser’s native context menu can be accessed by holding down
``Shift`` and right-clicking:

.. raw:: html

  <div class="jp-youtube-video">
    <iframe src="https://www.youtube-nocookie.com/embed/XPPWW-7WJ40?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  </div>

.. _shortcuts:

Keyboard Shortcuts
~~~~~~~~~~~~~~~~~~

.. _shortcuts-settings:

As in the classic Notebook, you can navigate the user interface through keyboard
shortcuts. You can find and customize the current list of keyboard shortcuts by
selecting the Advanced Settings Editor item in the Settings menu, then selecting
Keyboard Shortcuts in the Settings tab.

.. raw:: html

    <div class="jp-youtube-video">
       <iframe src="https://www.youtube-nocookie.com/embed/rhW3kAExCik?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
    </div>

.. _editor-keymaps:

You can also customize the :ref:`text editor <file-editor>` to use vim, emacs, or Sublime Text
keyboard maps by using the Text Editor Key Map submenu in the Settings
menu:

.. raw:: html

    <div class="jp-youtube-video">
       <iframe src="https://www.youtube-nocookie.com/embed/COheO7sA4-U?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
    </div>

.. _urls:

URLs (``/tree``, ``/workspaces``, etc.)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _url-tree:

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 combined in URLs that open a
specific file in a specific workspace. JupyterLab's file navigation URLS adopts
the nomenclature of the classic notebook; these URLs are ``/tree`` URLs:

.. code-block:: none

  http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb


.. _url-workspaces:

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* is not named, it is simply the main ``/lab`` URL:

.. code-block:: none

  http(s)://<server:port>/<lab-location>/lab

All other workspaces are named in the URL:

.. code-block:: none

  http(s)://<server:port>/<lab-location>/lab/workspaces/foo
  http(s)://<server:port>/<lab-location>/lab/workspaces/bar
  http(s)://<server:port>/<lab-location>/lab/workspaces/baz

Unlike the default (``/lab``) workspace, which only saves its state on the
user's local browser, named workspaces save their state on the server, so a
named workspace URL can be shared between multiple users (or browsers) as long
as they have access to the same server.

.. _url-clone:

One useful feature of workspaces is the ability to ``clone`` the contents of a
workspace into a new workspace.

* To copy the contents of the workspace ``foo`` into the workspace ``bar``:
  ``/lab/workspaces/bar?clone=foo``
* To copy the contents of the default workspace into the workspace ``foo``:
  ``/lab/workspaces/foo?clone``
* To copy the contents of the workspace ``foo`` into the default workspace:
  ``/lab?clone=foo``

.. _url-reset:

If something goes wrong with a workspace, or if simply needs to be cleared of
its contents, it can be ``reset``.

* To reset the contents of the workspace ``foo`` :
  ``/lab/workspaces/foo?reset``
* To reset the contents of the default workspace:
  ``/lab?reset``

These URL functions can be used separately as above, or in combination, *e.g.*:

* To reset the workspace ``foo`` and to load a specific notebook afterward:
  ``/lab/workspaces/foo/tree/path/to/notebook.ipynb?reset``
* To clone the contents of the workspace ``bar`` into the workspace ``foo`` and
  to load a notebook afterward:
  ``/lab/workspaces/foo/tree/path/to/notebook.ipynb?clone=bar``
* To reset the contents of the default workspace and to load a notebook:
  ``/lab/tree/path/to/notebook.ipynb?reset``