مطالعهٔ JupyterLab Docs
رابط کاربری ژوپیترلب، دفترچهها
باز کردن مرجع کامل دانلود آرشیو مستندات ناشر
گزیدهای از مستندات JupyterLab Docs · نسخهٔ c233d4b14d54 · BSD-3-Clause
رابط کاربری ژوپیترلب
% Copyright (c) Jupyter Development Team.
% Distributed under the terms of the Modified BSD License.
(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>.
:align: center
:alt: A screenshot of the default JupyterLab interface. The main work area is in the
: middle. There is also a left sidebar and a top menu bar.
:class: jp-screenshotJupyterLab sessions always reside in a {ref}workspace <workspaces>. Workspaces contain the state of JupyterLab: the files that are currently open, the layout of the application areas and tabs, etc. Workspaces can be saved on the server with {ref}named workspace URLs <url-workspaces> or {ref}using workspace commands <workspaces-gui> available in the menu and sidebar. To learn more about URLs in JupyterLab, visit {ref}urls.
In the user interface, the current workspace can be changed using the workspace selector widget located in the top bar.
To enable the workspace selector, use the main menu: View → Appearance → Show Workspace Indicator.
(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 folders
- 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.
(sidebars)=
Left and Right Sidebar
(left-sidebar)=
The left sidebar contains a number of commonly-used tabs including:
- a file browser,
- a list of tabs in the main work and of running kernels and terminals,
- the command palette (in 3.0+ moved to a modal window accessible with a {ref}
keyboard shortcut <access-palette>), - the {ref}
table of contents <toc>, - the {ref}
extension manager <extension-manager>.
:align: center
:alt: The left JupyterLab sidebar showing a variety of files in the file browser.
:class: jp-screenshot(right-sidebar)=
The right sidebar contains:
- the property inspector (active in notebooks), which includes the
{ref}metadata editor <metadata-editor> for viewing and modifying notebook and cell metadata,
- the {ref}
debugger <debugger>.
:align: center
:alt: The right JupyterLab sidebar showing the property inspector.
:class: jp-screenshotThe column that allows to switch between tabs is called Activity Bar in JupyterLab.
(left-sidebar-toggle)=
The sidebars can be collapsed or expanded by selecting "Show Left Sidebar" or "Show Right Sidebar" in the View menu or by clicking on the active sidebar tab:
The tabs can be moved between the left sidebar, the right sidebar, the {ref}main work area <main-area>, and the down area from the {ref}context menu <context-menus-rightclick>.
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/PlJGecfetek?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>JupyterLab extensions can add additional panels to the sidebars.
(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:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/Ka8qS7CO1XQ?rel=0&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).
Switching Tabs by Index
You can switch to a specific tab in the current tab bar using {kbd}Ctrl+Alt ({kbd}Cmd+Option on macOS) and a number from {kbd}1 to {kbd}8, where {kbd}1 is the first tab. {kbd}Ctrl+Alt+9 ({kbd}Cmd+Option+9 on macOS) activates the last tab in the current tab bar. When the main area is split into multiple panes, these shortcuts only switch tabs within the current pane. If the numbered tab does not exist in that pane, the shortcut does nothing.
On Windows, {kbd}Ctrl+Alt also acts as {kbd}AltGr. If your keyboard layout types a character for {kbd}AltGr and a number, such as [ and ] on a German keyboard, the shortcut with that number types the character instead of switching tabs. You can assign other keys in the {ref}keyboard shortcuts settings <user-shortcuts>.
(tabs)=
Tabs and Simple Interface Mode
The Tabs panel in the left sidebar lists the open documents or activities in the main work area:
:align: center
:alt: The tabs panel in JupyterLab with a list of sample documents.
:class: jp-screenshotThe same information is also available in the Tabs menu:
:align: center
:alt: The tabs menu in JupyterLab with a list of sample documents.
: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. Simple Interface mode enables this, while making it easy to return to your multi-activity layout in the main work area. Toggle Simple Interface mode using the View menu:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/DO7NOenMQC0?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>When you leave Simple Interface mode, the original layout of the main area is restored.
Searching
JupyterLab has an advanced built-in search plugin for finding text within a notebook or other document, which uses the Ctrl+F (Cmd+F for macOS) shortcut by default.
Your browser's find function will give unexpected results because it doesn't have access to the full content of a document (by default), but you can still use your browser find function from the browser menu if you want, or you can disable the built-in search shortcut using the Advanced Settings Editor.
Alternatively, you can disable windowed notebook rendering to expose the full document content to the browser at the expense of performance.
(settings-editor-tags)=
Finding Settings by Tag
In the Settings Editor, a search starting with tag: lists only the settings with a matching tag. The search box suggests the available tags as you type. JupyterLab exposes some tags in its settings:
tag:accessibility: settings that help with accessibility, such as the theme or zooming withCtrl+ scroll.tag:performance: settings that affect performance, such as notebook windowing or the maximum number of rendered outputs.
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:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/y30fs6kg6fc?rel=0&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:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/XPPWW-7WJ40?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(user-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.
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/rhW3kAExCik?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>Assigning a shortcut to a command without a default
Not every command has a default keyboard shortcut. For example, New Console for Notebook (available from a notebook's right-click menu) has no shortcut assigned out of the box, but you can add one yourself in either of two ways.
The quickest way is the add-shortcut tool in the Keyboard Shortcuts settings: click the + button in the toolbar at the top of the shortcuts list, search for the command by name, and press the key combination you want to assign. Conflicts with existing shortcuts are flagged as you type so you can adjust your choice.
Alternatively, you can define the keybinding in JSON using the Advanced Settings Editor, which is convenient when you want to copy settings between installations. Add an entry that pairs the command's id with the keys you want:
{
"shortcuts": [
{
"command": "notebook:create-console",
"keys": ["Accel Shift J"],
"selector": ".jp-Notebook.jp-mod-commandMode"
}
]
}With this setting, pressing {kbd}Ctrl+Shift+J ({kbd}Cmd+Shift+J on macOS) while a notebook is focused in command mode opens a console attached to it. Accel maps to {kbd}Cmd on macOS and {kbd}Ctrl on other platforms.
To find a command's id, browse the {ref}command list <commands> or the existing entries in the Keyboard Shortcuts settings. When editing the JSON directly, choose a key combination that is not already bound in the same context.
Defining shortcuts running multiple commands (macros)
To define a custom keyboard shortcut which runs more than one command, add a keyboard shortcut for apputils:run-all-enabled command in Keyboard Shortcuts advanced settings. The commands you wish to run are passed in the args argument as a list of strings:
{
"shortcuts": [
{
"command": "apputils:run-all-enabled",
"keys": ["Accel T"],
"args": {
"commands": ["docmanager:save", "application:close"]
},
"selector": "body"
}
]
}In this example docmanager:save and application:close commands are mapped to Accel T. The commands are run in succession when you use the shortcut.
Shortcuts for R operators
JupyterLab provides shortcuts for operators that are common in R when an editor using the R language is active. Press {kbd}Alt+- ({kbd}Option+- on macOS) to insert <-, or {kbd}Ctrl+Shift+M ({kbd}Cmd+Shift+M on macOS) to insert %>%. These shortcuts are scoped to R language editors, so they do not affect editors using another language.
To replace %>% with R's native pipe |>, use the following Keyboard Shortcuts settings. First disable the built-in bindings using their exact keys and selectors, then add a macro scoped to R editors:
{
"shortcuts": [
{
"command": "console:replace-selection",
"keys": ["Accel Shift M"],
"selector": ".jp-CodeConsole-promptCell [data-jp-editor-language='r']",
"disabled": true
},
{
"command": "fileeditor:replace-selection",
"keys": ["Accel Shift M"],
"selector": ".jp-FileEditor [data-jp-editor-language='r']",
"disabled": true
},
{
"command": "notebook:replace-selection",
"keys": ["Accel Shift M"],
"selector": ".jp-Notebook.jp-mod-editMode [data-jp-editor-language='r']",
"disabled": true
},
{
"command": "apputils:run-first-enabled",
"keys": ["Accel Shift M"],
"args": {
"commands": [
"console:replace-selection",
"fileeditor:replace-selection",
"notebook:replace-selection"
],
"args": { "text": "|> " }
},
"selector": "[data-jp-editor-language='r']"
}
]
}run-first-enabled sends the replacement to the first command that is available in the current context. Use the same pattern to customize Alt -. In the settings, Alt is the {kbd}Option key on macOS, and Accel maps to {kbd}Cmd on macOS and {kbd}Ctrl on other platforms.
Markdown editing shortcuts
When editing markdown cells, you can use {kbd}Ctrl+B ({kbd}Cmd+B on macOS) to toggle bold formatting. Select text in a markdown cell and press {kbd}Ctrl+B to wrap it with ** for bold formatting. Pressing {kbd}Ctrl+B again on already bold text (text wrapped with **) will remove the bold formatting.
(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:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/COheO7sA4-U?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>دفترچهها
% Copyright (c) Jupyter Development Team.
% Distributed under the terms of the Modified BSD License.
(user-notebook)=
# Notebooks
Jupyter notebooks are documents that combine live runnable code with narrative text (Markdown), equations (LaTeX), images, interactive visualizations and other rich output:
:align: center
:alt: JupyterLab with notebook titled Data.ipynb open. This notebook has text, code,
: an imported CSV, and an interactive map all in one.
:class: jp-screenshotJupyter notebooks (.ipynb files) are fully supported in JupyterLab. The notebook document format used in JupyterLab is the same as in the classic Jupyter Notebook. Your existing notebooks should open correctly in JupyterLab. If they don’t, please open an issue on our GitHub issues page.
(create-notebook)=
Create a notebook by clicking the + button in the file browser and then selecting a kernel in the new Launcher tab:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/QL0IxDAOEc0?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(rename-file)=
A new file is created with a default name. Rename a file by right-clicking on its name in the file browser and selecting “Rename” from the context menu:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/y3xzXelypjs?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>The user interface for notebooks in JupyterLab closely follows that of the classic Jupyter Notebook. The keyboard shortcuts of the classic Notebook continue to work (with command and edit mode). However, a number of new things are possible with notebooks in JupyterLab.
Edit Mode vs Command Mode
JupyterLab notebooks operate in two primary modes: Edit Mode and Command Mode.
Edit Mode
- Used to edit the contents of a cell.
- Activated by pressing {kbd}
Enteron a selected cell. - A blue cell border indicates Edit Mode.
- Keyboard input affects the cell contents.
Command Mode
- Used to perform notebook-level actions such as running cells, adding cells, or changing cell types.
- Activated by pressing {kbd}
Escwhen not editing text. - A gray cell border indicates Command Mode.
- Keyboard shortcuts act on entire cells rather than their contents.
Pressing {kbd}Esc exits Edit Mode, while pressing {kbd}Enter enters Edit Mode on the selected cell.
Working with Cells
Open the Property Inspector from the View menu and expand Common Tools to view properties for the active cell. The Cell ID field shows the active cell's identifier and provides buttons to copy either the identifier or a direct link to that cell. These direct links use the #cell-id=<cell-id> syntax described in {ref}urls.
(drag-drop)=
Drag and drop cells to rearrange your notebook:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/J9xoTGdqWIo?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(drag-copy)=
Drag cells between notebooks to quickly copy content:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/YTNZ5TS2LfU?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(multiple-views)=
Create multiple synchronized views of a single notebook:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/SQn9aRc050w?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(collapse-code)=
Collapse and expand code and output using the View menu or the blue collapser button on left of each cell:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/WgiX3ZRaTiY?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(enable-scrolling)=
Enable scrolling for long outputs by right-clicking on a cell and selecting “Enable Scrolling for Outputs”:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/U4usAUZCv_c?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(cell-output-mirror)=
Create a new synchronized view of a cell’s output:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/Asa_ML45HP8?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(tab-completion)=
Tab completion (activated with the Tab key) can now include additional information about the types of the matched items:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/MuNr0i8LgpM?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>Note: IPython 6.3.1 has temporarily disabled type annotations. To re-enable them, add c.Completer.use_jedi = True to an ipython_config.py file.
(user-tooltip)=
The tooltip (activated with Shift Tab) contains additional information about objects:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/TgqMK1SG7XI?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(create-console)=
You can connect a {ref}code console <code-console> to a notebook kernel to have a log of computations done in the kernel, in the order in which they were done. The attached code console also provides a place to interactively inspect kernel state without changing the notebook. Right-click on a notebook and select “New Console for Notebook”:
<div class="jp-youtube-video">
<iframe src="https://www.youtube-nocookie.com/embed/eq1l7DBngQQ?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
</div>(kernel-history)=
You can iterate through the kernel history in a document cell using Alt Up-Arrow and Alt Down-Arrow. To use this feature, enable kernel history access in the notebook settings.
(cell-toolbar)=
Cell Toolbar
In each cell, there is a toolbar that provides quick access to commonly-used functions, if there is enough room to display it on the first line.
If you would like to disable the cell toolbar, open the Settings Editor, choose the Cell Toolbar in the left panel, and uncheck "Show cell toolbar".
Administrators can turn off the cell toolbar by disabling its extension, by running:
jupyter labextension disable @jupyterlab/cell-toolbar-extensionon the command line. Administrators can turn it back on by running:
jupyter labextension enable @jupyterlab/cell-toolbar-extension(notebook-trust)=
Trust
JavaScript and HTML in notebooks created on other machines are not trusted, which results in sanitization of HTML and interactive outputs not being displayed until the notebook is explicitly trusted.
The trust status of the active notebook is indicated by a shield icon in the status bar; a checkmark ({{ trusted }}) in the shield indicates a trusted notebook while a cross ({{ not_trusted }}) indicates an untrusted notebook. To trust a notebook (and render any blocked outputs) use the Trust Notebook command available in the {ref}command palette <commands>.
JupyterLab follows the Jupyter Notebook's Security Model where any output generated by the current user is trusted, with following implementation details of relevance to advanced users:
- manually re-running a non-trusted cell will mark it as trusted,
- if any of the code cells is not trusted, the entire notebook is considered
not trusted and none of the outputs will be trusted upon reopening it (while it is unusual to see a notebook with a single untrusted cell, this can occur when copy-pasting cells from an untrusted notebook),
- only code cells can be trusted; the Markdown cells are always sanitised.
(plotting)=
Plotting and Visualization
JupyterLab supports data visualization using libraries like matplotlib, plotly, and others.
Static Plots with IPython Kernel
For static plots in JupyterLab with IPython kernel, simply import and use your plotting library of choice - no magic commands are needed:
plt.plot([1, 2, 3, 4])
plt.ylabel("some numbers")
plt.show()Unlike classic Jupyter Notebook, JupyterLab with IPython kernel displays matplotlib plots automatically
without requiring `%matplotlib inline`.Interactive Plots, Widgets or Plotting with Other Kernels
Interactive plots, widgets, or plotting with other kernels may require additional packages to be installed and sometimes a magic command or other kernel native instructions (please refer to the respective library documentation). Common options include:
Python:
- ipywidgets - Interactive widgets for Jupyter notebooks
- ipympl - Interactive matplotlib backend
- plotly - Interactive plotting library
- bokeh - Interactive visualization library
- altair - Declarative visualization library
R:
- ggplot2 - Grammar of graphics for R
Mermaid diagrams
JupyterLab includes built-in support for rendering Mermaid diagrams in Markdown cells.
Mermaid diagrams can be added using fenced code blocks with the mermaid language identifier:
graph TD A --> B
which renders as:
graph TD
A --> BMermaid support is bundled with JupyterLab and does not require installing an additional extension.
Mermaid diagrams are rendered automatically in Markdown cells in notebooks opened in JupyterLab. The diagram source remains visible when editing the Markdown cell.
(paste-code-cells-without-output)=
Paste code cells without output
When Paste code cells without output is enabled in Settings → JupyterLab Notebook (or Settings → Notebook), pasting code cells inserts only the cell content, not the outputs. This is useful when you want pasted code to reflect only what was written, without carrying over previous run results.
(metadata-editor)=
Metadata Editor (Property Inspector)
The Property Inspector provides a metadata editor that allows you to view and modify the metadata of both the notebook and individual cells.
Opening the Metadata Editor
To access the metadata editor, click the gear icon in the right sidebar of an open notebook. This opens the Property Inspector panel.
The panel has two sections:
- Notebook Metadata: displays the metadata for the entire notebook
(e.g., kernel information, language info).
- Cell Metadata: displays the metadata for the currently selected cell
(e.g., tags, whether the cell can be edited or deleted).
Editing Metadata
The metadata is displayed as JSON that you can edit directly. After making changes:
:align: center
:alt: The Property Inspector showing the commit and revert icons for editing cell metadata
:class: jp-screenshot- Click the checkmark icon to commit your changes. This icon appears only once your edits are valid JSON.
- Click the revert icon to discard your changes and restore the
previous metadata.
For [notebook format metadata](https://nbformat.readthedocs.io/en/latest/format_description.html#cell-metadata)
fields such as `editable` and `deletable`, you can also use the toggle
controls in the "Common tools" section of the Property Inspector for a
more convenient editing experience.Common Metadata Fields
Some commonly used cell metadata fields include:
tags: a list of string tags for the cell, often used by tools like
nbconvert and papermill to control cell behavior during export or parameterized execution.
editable: controls whether the cell content can be modified.deletable: controls whether the cell can be deleted.
Be cautious when editing metadata directly, as incorrect values may
affect notebook behavior. If something goes wrong, use the revert icon
to undo your changes before committing them.