Getting Started With JupyterLab

jupyterlab is the latest package from project jupyter. in some ways, it is kind of a replacement for jupyter notebook. however the jupyter notebook is a separate project from jupyterlab. i like to think of jupyterlab as a kind of web-based integrated development environment that you an use to to work with jupyter notebooks as well as using terminals, text editors, and code consoles. you might say jupyterlab is a more powerful version of jupyter notebook.

anyway, here are a few of the things that jupyterlab is capable of:

• code consoles - these are coding scratchpads that you can use for running code interactively, kind of like python's idle.
• kernel-backed documents - these allow you to enable code in any text file (markdown, python, r, etc.) that can then be run in the jupyter kernel.
• mirrored notebook cell outputs - this let's you create simple dashboards.
• multiple views of the same document - gives you the ability to live edit documents and see the results in real-time.

jupyterlab will allow you to view and handle multiple types of data. you can also display rich output from these formats using various visualizations or markdown.

for navigation, you can use customizable keyboard shortcuts or key maps from vim, emacs, and even sublimetext.

you can add new behavior to your jupyterlab instance via extensions. this includes theming support, file editors, and more.

installation

you can use conda, pip, or pipenv to install jupyterlab.

conda

if you are an anaconda user, then you can use conda for installation purposes by using the following command:

conda install -c conda-forge jupyterlab

pip

if you prefer using python's native installer, pip, then this is the command you want:

pip install jupyterlab

note: if you are using pip install -user , then you will need to add the user-level "bin" directory to your path environment variable to be able to launch jupyterlab.

pipenv

the pipenv tool is a new package that can be used to create a python virtual environment and download a package into it. if you happen to have it installed, then you can use the following two commands to get jupyterlab:

pipenv install jupyterlab
pipenv shell

note that calling the shell command is required if you want to launch jupyterlab from within the virtualenv that you installed it into.

running jupyterlab

now that we have jupyterlab installed, we should try running it. you can use either jupyter-lab or jupyter lab to run it. when i ran either of these commands, i got the following initial web application:

initial landing page for a new jupyterlab

the tab on the right is called the launcher . this is one place you can go to start a new notebook, code console, terminal, or text file. new documents are opened as new tabs. you will note that when you create a new notebook or other item that the launcher disappears. if you would like to open a second document, just click the "+" button on the left, which i have circled below:

adding a new item in jupyterlab

let's open a notebook and then click the plus button. if you do that, your screen should look something like this:

multiple tools in jupyterlab

you can also create new items by using the **menu** that runs along the top of the screen. just go to **file** -> **new** and then choose the type of item you would like to create. most of the menu items should be familiar to you if you have used jupyter notebook. there are some new entries here that are specific to jupyterlab, however. for example:

• new launcher - launches a new launcher.
• open from path - opens a document from a path other than the one you started in.
• save notebook as... - let's you save the currently selected notebook with a new filename.
• export notebook as... - let's you export your notebook to a different format, such as pdf, markdown, etc.

explore the menu and see what else you can find. it's pretty self-explanatory.

the file browser

the tree on the left is known as the file browser . it shows you the files that are available to you from the location that you launched jupyterlab from. just click the folder icon to make the tree collapse so that the tab can fill the browser:

file browser minimized

you will note that you can create new folders in the file browser as well by clicking the folder+ icon (circled below):

creating a new folder

if you need to add a file to jupyterlab from another location on your computer, then you will want to click on the upload button:

uploading/saving a file to the workspace

when you do, it will pop open a file open dialog:

upload dialog

just use this as you would if you were opening a file in another program. just remember that instead of opening a file, you are "uploading" or "copying" it to your jupyterlab workspace.

finally, there is a refresh button that you can use to refresh the workspace if you happened to copy a file into the workspace by using a method other than the upload button:

refresh file browser button

special urls

as with jupyter notebook, jupyterlab allows users to copy urls into the browser to open a specific notebook or file. however, jupyterlab has also added the ability to manage workspaces and file navigation via urls.

for example, if you want to use file navigation, you can use the special keyword tree to do so. here is an example url using an untitled notebook:

http://localhost:8888/lab/tree/untitled.ipynb

if you were to try this out, you would see the normal jupyter notebook interface instead of seeing the notebook inside of jupyterlab.

workspaces

the default workspace doesn't have a name, but it can be found at /lab . if you would like to clone your workspace, you can use the following format:

http://localhost:8888/lab/workspaces/test ?clone

this will copy your current workspace into a workspace named test . if you want to copy the test workspace into your default workspace, the url would look like this:

http://localhost:8888/lab?clone=test

you can also reset a workspace using the reset url parameter. when you reset a workspace, you are clearing it of its contents. here is an example of resetting the default workspace:

http://localhost:8888/lab/workspaces/lab?reset

the cell inspector

let's create a notebook inside of our jupyterlab instance. go to the launcher and choose a kernel. you will have python 2 or python 3 by default. once you have created it, you should see a new tab named "untitled.ipynb" like this:

an empyt notebook in jupyterlab

as you can see, we have a notebook with a single cell. let's add the following code to the slide:

def adder(a, b):
   return a + b
 
adder(2, 3)

now let's click the little wrench that is in the toolbar on the left. here's a screenshot with the button circled:

the cell inspector

when you click that wrench, your screen should look like the above. this is called the cell inspector . this is where you can set up your notebook for presentation purposes. you can set which cells are slides or sub-slides. pretty much anything that we talked about in chapter 9 relating to the notebook itself can also be done here. you will also note that the cell inspector will display any metadata that jupyterlab/notebook is adding to the cells.

if you would like to see that in action, then try setting your first cell to a slide . now you should see the metadata field populated like this:

the cell's metadata

using files

you can use jupyterlab's file browser and file menu to work with files and directories on your system. this allows you to open, create, delete, rename, download/upload, copy, and share files and directories. you can find the file browser in the left sidebar:

the file browser

if you have files in your browser, you can open it by just double-clicking the file as you would normally do in your system's file browser. you may also drag a file from the file browser into the work area (on the right) which will cause it to open.

many of the file types that jupyterlab supports also have multiple viewers and editors. you can open a markdown file in an editor or view it as html, for example. if you want to open the file in a non-default viewer/editor, just right-click the file and choose "open with..." from the context menu:

context menu for files

note that you can open a single file into multiple viewers/editors and they will remain in sync.

the text editor

jupyterlab comes with a built-in text editor that you can use to create or open text files. open up the launcher and instead of creating a notebook, go to the bottom of the launcher and create a text file.

launch the text editor

it will create an untitled.txt file by default. but you can go to the file menu and use "save as..." to save it as something else. this allows you to create python files, markdown, and pretty much anything else you would like to. it even provides syntax highlighting for some file types, although code completion is not supported. you may also create files via the file menu.

the text editor also supports configurable indentation (tabs vs. spaces), key maps, and basic theming. just go to the settings menu to view or edit them:

file settings

if you would like to edit an existing text file, all you need to do is double-click it in the file browser.

interactive code consoles

one of the newer features to jupyterlab is the code console , which is basically a repl in your browser. it will let you run code interactively in the currently selected kernel. the "cells" of a code console show the order in which the code was run. to create a new code console, click the "+" button in the file browser and select the kernel of your choice:

code console launcher

enter some code. here's an example if you are having some trouble thinking of any on your own:

print('hello console!')

now press shift+enter to run the code. you should see the following output if everything worked correctly:

code console

code completion works via the tab key. you can also bring up tooltips by pressing shift+tab .

if you need to clear the code console without restarting the kernel, you can right click on the console itself and select "clear console cells."

terminals

the jupyterlab project continues its support of system shells in the browser. for mac/linux, it supports bash, tsch, etc., while on windows it supports powershell. these terminals can run anything that you would normally run from your system's terminal, including other programs like vim or emacs. do note that the jupyterlab terminals run on the system that you have jupyterlab installed to, so it will be using your user's privileges as well.

anyway, if you would like to see a terminal in action, just start up the launcher by pressing the "+" button in the file browser. then select the terminal:

terminal launcher

if you close the terminal tab, jupyterlab will leave it running in the background. here is a terminal running:

a running terminal

if you would like to re-open your terminal, just go to the running tab:

running apps

then select the terminal from the list of running applications.

the command palette

the user actions in jupyterlab all go through a central command system. this includes the commands used by the menu bar, context menus, keyboard shortcuts, and more. you can access the available commands via the command palette , which you will find under the commands tab:

the command palette

here you can search for commands and execute them directly instead of hunting for them in the menu system. you can also bring up the command palette with the following keyboard shortcut: command/ctrl shift c .

supported file types

jupyterlab supports quite a few filetypes that it can display or allow you to edit. this allows you to layout rich cell output in a notebook or code console. for files, jupyterlab will detect the data format by looking at the extension of the file or the entire filename if the extensions does not exist. note that multiple editors/viewers can be associated with a single file type. for example, you can edit a markdown file and view it as html. just right-click a file and go to the open with context menu item to view the editors and viewers that are available to you for that file type:

using open with

you can use python code to display different data formats in your notebook or code console. here is an example:

from ipython.display import display, html
display(html('<h1>hello from jupyterlab</h1>'))

when you run this code in a notebook, it should look like this:

running html in a notebook

for a full list of file types that are supported by jupyterlab, i recommend checking out the documentation . this should always be up-to-date and more useful then if i were to list out the items myself.

a word on extensions

as you might expect, jupyterlab supports extensions and was designed with extensibility in mind. extensions can customize the user's experience or enhance one or more parts of jupyterlab. for example, you could add new items to the menu or command palette or add some new keyboard shortcuts. jupyterlab itself is actually a collection of extensions.

if you want to create an extension for jupyterlab, then you will need to be familiar with javascript or be willing to learn. the extensions need to be in the npm packaging format. to install pre-made extensions, you are required to have node.js installed on your machine. be sure to check out their website for proper installation instructions for your operating system.

installing/uninstalling extensions

once you have node.js installed, then you can install an extension to jupyterlab by running the following command:

jupyter labextension install the-extension-name

if you require a specific version of the extension, then the command would look like this:

jupyter labextension install the-extension-name@1.2

where "1.2" is the version you require. you can also extensions that are gzipped tarballs or a url to a gzipped tarball.

to get a list of currently installed jupyterlab extensions, just run:

jupyter labextension list

in the event that you want to uninstall an extension, you can easily do so like this:

jupyter labextension uninstall the-extension-name

you may also install or uninstall multiple extensions by listing the names of the packages after the install or uninstall command. since jupyterlab rebuilds after each installation, this can take quite a while. to speed things up a bit when installing or uninstalling multiple extensions, you can include the **-no-build** flag. then once the installation or uninstall is complete, you will need to run the build command yourself, like this:

jupyter lab build

disabling extensions

if you don't want to uninstall an extension but you would like to disable it, that is easy to do too. just run the disable command:

jupyter labextension disable the-extension-name

then when you want to re-enable it, you can run the enable command:

jupyter labextension enable the-extension-name

wrapping up

the jupyterlab package is really amazing. you can do a lot more with it than you could with just a jupyter notebook. however the user interface is also more complex so the learning curve will be a bit steeper. however, i think it is worth learning how to use it as the ability to edit documents and view them live is really helpful when creating a presentation or doing other types of work. at the very least, i would give it a try in a virtual environment to see whether or not it will fit your workflow.