Main features of the web application#

• In-browser editing for code, with automatic syntax highlighting,indentation, and tab completion/introspection.

• The ability to execute code from the browser, with the results ofcomputations attached to the code which generated them.

• Displaying the result of computation using rich media representations, suchas HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figuresrendered by the [matplotlib] library, can be included inline.

• In-browser editing for rich text using the [Markdown] markup language, whichcan provide commentary for the code, is not limited to plain text.

• The ability to easily include mathematical notation within markdown cellsusing LaTeX, and rendered natively byMathJax.

Notebook documents#

Notebook documents contains the inputs and outputs of a interactive session aswell as additional text that accompanies the code but is not meant forexecution. In this way, notebook files can serve as a complete computationalrecord of a session, interleaving executable code with explanatory text,mathematics, and rich representations of resulting objects. These documentsare internallyJSON files and are saved with the.ipynb extension. SinceJSON is a plain text format, they can be version-controlled and shared withcolleagues.

Notebooks may be exported to a range of static formats, including HTML (forexample, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, viathe [nbconvert] command.

Furthermore, any.ipynb notebook document available from a publicURL can be shared via the Jupyter Notebook Viewer <nbviewer>.This service loads the notebook document from the URL and renders it as astatic web page. The results may thus be shared with a colleague, or as apublic blog post, without other users needing to install the Jupyter notebookthemselves. In effect, nbviewer is simply [nbconvert] asa web service, so you can do your own static conversions with nbconvert,without relying on nbviewer.

Notebooks and privacy#

Because you use Jupyter in a web browser, some people are understandablyconcerned about using it with sensitive data.However, if you followed the standardinstall instructions,Jupyter is actually running on your own computer.If the URL in the address bar starts withhttp://localhost: orhttp://127.0.0.1:, it’s your computer acting as the server.Jupyter doesn’t send your data anywhere else—and as it’s open source,other people can check that we’re being honest about this.

You can also use Jupyter remotely:your company or university might run the server for you, for instance.If you want to work with sensitive data in those cases,talk to your IT or data protection staff about it.

We aim to ensure that other pages in your browser or other users on the samecomputer can’t access your notebook server. See thesecurity documentation formore about this.

Creating a new notebook document#

A new notebook may be created at any time, either from the dashboard, or usingtheFile ‣ New menu option from within an active notebook.The new notebook is created within the same directory and will open in a newbrowser tab. It will also be reflected as a new entry in the notebook list onthe dashboard.

Opening notebooks#

An open notebook hasexactly one interactive session connected to akernel, which will execute code sent by the userand communicate back results. This kernel remains active if the web browserwindow is closed, and reopening the same notebook from the dashboard willreconnect the web application to the same kernel. In the dashboard, notebookswith an active kernel have aShutdown button next to them, whereasnotebooks without an active kernel have aDelete button in its place.

Other clients may connect to the same kernel.When each kernel is started, the notebook server prints to the terminal amessage like this:

[JupyterNotebookApp]Kernelstarted:87f7d2c0-13e3-43df-8bb8-1bd37aaf3373

This long string is the kernel’s ID which is sufficient for getting theinformation necessary to connect to the kernel. If the notebook uses the IPythonkernel, you can also see thisconnection data by running the%connect_infomagic, which will print the same ID information along with otherdetails.

You can then, for example, manually start a Qt console connected to thesamekernel from the command line, by passing a portion of the ID:

$ jupyter qtconsole --existing 87f7d2c0

Without an ID,--existing will connect to the most recentlystarted kernel.

With the IPython kernel, you can also run the%qtconsolemagic in the notebook to open a Qt console connectedto the same kernel.

Code cells#

Acode cell allows you to edit and write new code, with full syntaxhighlighting and tab completion. The programming language you use dependson thekernel, and the default kernel (IPython) runs Python code.

When a code cell is executed, code that it contains is sent to the kernelassociated with the notebook. The results that are returned from thiscomputation are then displayed in the notebook as the cell’soutput. Theoutput is not limited to text, with many other possible forms of output arealso possible, includingmatplotlib figures and HTML tables (as used, forexample, in thepandas data analysis package). This is known as IPython’srich display capability.

Markdown cells#

You can document the computational process in a literate way, alternatingdescriptive text with code, usingrich text. In IPython this is accomplishedby marking up text with the Markdown language. The corresponding cells arecalledMarkdown cells. The Markdown language provides a simple way toperform this text markup, that is, to specify which parts of the text shouldbe emphasized (italics), bold, form lists, etc.

If you want to provide structure for your document, you can use markdownheadings. Markdown headings consist of 1 to 6 hash # signs# followed by aspace and the title of your section. The markdown heading will be convertedto a clickable link for a section of the notebook. It is also used as a hintwhen exporting to other document formats, like PDF.

When a Markdown cell is executed, the Markdown code is converted intothe corresponding formatted rich text. Markdown allows arbitrary HTML code forformatting.

Within Markdown cells, you can also includemathematics in a straightforwardway, using standard LaTeX notation:$...$ for inline mathematics and$$...$$ for displayed mathematics. When the Markdown cell is executed,the LaTeX portions are automatically rendered in the HTML output as equationswith high quality typography. This is made possible byMathJax, whichsupports alarge subset of LaTeX functionality

Standard mathematics environments defined by LaTeX and AMS-LaTeX (theamsmath package) also work, such as\begin{equation}...\end{equation}, and\begin{align}...\end{align}.New LaTeX macros may be defined using standard methods,such as\newcommand, by placing them anywherebetween math delimiters ina Markdown cell. These definitions are then available throughout the rest ofthe IPython session.

Raw cells#

Raw cells provide a place in which you can writeoutput directly.Raw cells are not evaluated by the notebook.When passed through [nbconvert], raw cells arrive in thedestination format unmodified. For example, you can type full LaTeXinto a raw cell, which will only be rendered by LaTeX after conversion bynbconvert.

Keyboard shortcuts#

All actions in the notebook can be performed with the mouse, but keyboardshortcuts are also available for the most common ones. The essential shortcutsto remember are the following:

• Shift-Enter: run cell: Execute the current cell, show any output, and jump to the next cell below.IfShift-Enter is invoked on the last cell, it makes a new cell below.This is equivalent to clicking theCell,Run menuitem, or the Play button in the toolbar.

• Esc: Command mode: In command mode, you can navigate around the notebook using keyboard shortcuts.

• Enter: Edit mode: In edit mode, you can edit text in cells.

For the full list of available shortcuts, clickHelp,Keyboard Shortcuts in the notebook menus.