You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
267 lines
8.3 KiB
267 lines
8.3 KiB
|
|
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Notebook%20Basics.ipynb>`__
|
|
|
|
Notebook Basics
|
|
===============
|
|
|
|
Running the Notebook Server
|
|
---------------------------
|
|
|
|
The Jupyter notebook server is a custom web server that runs the
|
|
notebook web application. Most of the time, users run the notebook
|
|
server on their local computer using the command line interface.
|
|
|
|
Starting the notebook server using the command line
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can start the notebook server from the command line (Terminal on
|
|
Mac/Linux, CMD prompt on Windows) by running the following command:
|
|
|
|
::
|
|
|
|
jupyter notebook
|
|
|
|
This will print some information about the notebook server in your
|
|
terminal, including the URL of the web application (by default,
|
|
``http://127.0.0.1:8888``). It will then open your default web browser
|
|
to this URL.
|
|
|
|
When the notebook opens, you will see the **notebook dashboard**, which
|
|
will show a list of the notebooks, files, and subdirectories in the
|
|
directory where the notebook server was started (as seen in the next
|
|
section, below). Most of the time, you will want to start a notebook
|
|
server in the highest directory in your filesystem where notebooks can
|
|
be found. Often this will be your home directory.
|
|
|
|
Additional options
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
By default, the notebook server starts on port 8888. If port 8888 is
|
|
unavailable, the notebook server searchs the next available port.
|
|
|
|
You can also specify the port manually:
|
|
|
|
::
|
|
|
|
jupyter notebook --port 9999
|
|
|
|
Or start notebook server without opening a web browser.
|
|
|
|
::
|
|
|
|
jupyter notebook --no-browser
|
|
|
|
The notebook server has a number of other command line arguments that
|
|
can be displayed with the ``--help`` flag:
|
|
|
|
::
|
|
|
|
jupyter notebook --help
|
|
|
|
The Notebook dashboard
|
|
----------------------
|
|
|
|
When you first start the notebook server, your browser will open to the
|
|
notebook dashboard. The dashboard serves as a home page for the
|
|
notebook. Its main purpose is to display the notebooks and files in the
|
|
current directory. For example, here is a screenshot of the dashboard
|
|
page for the ``examples`` directory in the Jupyter repository:
|
|
|
|
The top of the notebook list displays clickable breadcrumbs of the
|
|
current directory. By clicking on these breadcrumbs or on
|
|
sub-directories in the notebook list, you can navigate your file system.
|
|
|
|
To create a new notebook, click on the "New" button at the top of the
|
|
list and select a kernel from the dropdown (as seen below). Which
|
|
kernels are listed depend on what's installed on the server. Some of the
|
|
kernels in the screenshot below may not exist as an option to you.
|
|
|
|
Notebooks and files can be uploaded to the current directory by dragging
|
|
a notebook file onto the notebook list or by the "click here" text above
|
|
the list.
|
|
|
|
The notebook list shows green "Running" text and a green notebook icon
|
|
next to running notebooks (as seen below). Notebooks remain running
|
|
until you explicitly shut them down; closing the notebook's page is not
|
|
sufficient.
|
|
|
|
To shutdown, delete, duplicate, or rename a notebook check the checkbox
|
|
next to it and an array of controls will appear at the top of the
|
|
notebook list (as seen below). You can also use the same operations on
|
|
directories and files when applicable.
|
|
|
|
To see all of your running notebooks along with their directories, click
|
|
on the "Running" tab:
|
|
|
|
This view provides a convenient way to track notebooks that you start as
|
|
you navigate the file system in a long running notebook server.
|
|
|
|
Overview of the Notebook UI
|
|
---------------------------
|
|
|
|
If you create a new notebook or open an existing one, you will be taken
|
|
to the notebook user interface (UI). This UI allows you to run code and
|
|
author notebook documents interactively. The notebook UI has the
|
|
following main areas:
|
|
|
|
- Menu
|
|
- Toolbar
|
|
- Notebook area and cells
|
|
|
|
The notebook has an interactive tour of these elements that can be
|
|
started in the "Help:User Interface Tour" menu item.
|
|
|
|
Modal editor
|
|
------------
|
|
|
|
Starting with IPython 2.0, the Jupyter Notebook has a modal user
|
|
interface. This means that the keyboard does different things depending
|
|
on which mode the Notebook is in. There are two modes: edit mode and
|
|
command mode.
|
|
|
|
Edit mode
|
|
~~~~~~~~~
|
|
|
|
Edit mode is indicated by a green cell border and a prompt showing in
|
|
the editor area:
|
|
|
|
When a cell is in edit mode, you can type into the cell, like a normal
|
|
text editor.
|
|
|
|
.. raw:: html
|
|
|
|
<div class="alert alert-success">
|
|
|
|
Enter edit mode by pressing ``Enter`` or using the mouse to click on a
|
|
cell's editor area.
|
|
|
|
.. raw:: html
|
|
|
|
</div>
|
|
|
|
Command mode
|
|
~~~~~~~~~~~~
|
|
|
|
Command mode is indicated by a grey cell border:
|
|
|
|
When you are in command mode, you are able to edit the notebook as a
|
|
whole, but not type into individual cells. Most importantly, in command
|
|
mode, the keyboard is mapped to a set of shortcuts that let you perform
|
|
notebook and cell actions efficiently. For example, if you are in
|
|
command mode and you press ``c``, you will copy the current cell - no
|
|
modifier is needed.
|
|
|
|
.. raw:: html
|
|
|
|
<div class="alert alert-error">
|
|
|
|
Don't try to type into a cell in command mode; unexpected things will
|
|
happen!
|
|
|
|
.. raw:: html
|
|
|
|
</div>
|
|
|
|
.. raw:: html
|
|
|
|
<div class="alert alert-success">
|
|
|
|
Enter command mode by pressing ``Esc`` or using the mouse to click
|
|
*outside* a cell's editor area.
|
|
|
|
.. raw:: html
|
|
|
|
</div>
|
|
|
|
Mouse navigation
|
|
----------------
|
|
|
|
All navigation and actions in the Notebook are available using the mouse
|
|
through the menubar and toolbar, which are both above the main Notebook
|
|
area:
|
|
|
|
The first idea of mouse based navigation is that **cells can be selected
|
|
by clicking on them.** The currently selected cell gets a grey or green
|
|
border depending on whether the notebook is in edit or command mode. If
|
|
you click inside a cell's editor area, you will enter edit mode. If you
|
|
click on the prompt or output area of a cell you will enter command
|
|
mode.
|
|
|
|
If you are running this notebook in a live session (not on
|
|
http://nbviewer.jupyter.org) try selecting different cells and going
|
|
between edit and command mode. Try typing into a cell.
|
|
|
|
The second idea of mouse based navigation is that **cell actions usually
|
|
apply to the currently selected cell**. Thus if you want to run the code
|
|
in a cell, you would select it and click the
|
|
|
|
.. raw:: html
|
|
|
|
<button class='btn btn-default btn-xs'>
|
|
|
|
.. raw:: html
|
|
|
|
</button>
|
|
|
|
button in the toolbar or the "Cell:Run" menu item. Similarly, to copy a
|
|
cell you would select it and click the
|
|
|
|
.. raw:: html
|
|
|
|
<button class='btn btn-default btn-xs'>
|
|
|
|
.. raw:: html
|
|
|
|
</button>
|
|
|
|
button in the toolbar or the "Edit:Copy" menu item. With this simple
|
|
pattern, you should be able to do most everything you need with the
|
|
mouse.
|
|
|
|
Markdown and heading cells have one other state that can be modified
|
|
with the mouse. These cells can either be rendered or unrendered. When
|
|
they are rendered, you will see a nice formatted representation of the
|
|
cell's contents. When they are unrendered, you will see the raw text
|
|
source of the cell. To render the selected cell with the mouse, click
|
|
the
|
|
|
|
.. raw:: html
|
|
|
|
<button class='btn btn-default btn-xs'>
|
|
|
|
.. raw:: html
|
|
|
|
</button>
|
|
|
|
button in the toolbar or the "Cell:Run" menu item. To unrender the
|
|
selected cell, double click on the cell.
|
|
|
|
Keyboard Navigation
|
|
-------------------
|
|
|
|
The modal user interface of the Jupyter Notebook has been optimized for
|
|
efficient keyboard usage. This is made possible by having two different
|
|
sets of keyboard shortcuts: one set that is active in edit mode and
|
|
another in command mode.
|
|
|
|
The most important keyboard shortcuts are ``Enter``, which enters edit
|
|
mode, and ``Esc``, which enters command mode.
|
|
|
|
In edit mode, most of the keyboard is dedicated to typing into the
|
|
cell's editor. Thus, in edit mode there are relatively few shortcuts. In
|
|
command mode, the entire keyboard is available for shortcuts, so there
|
|
are many more. The ``Help``->``Keyboard Shortcuts`` dialog lists the
|
|
available shortcuts.
|
|
|
|
We recommend learning the command mode shortcuts in the following rough
|
|
order:
|
|
|
|
1. Basic navigation: ``enter``, ``shift-enter``, ``up/k``, ``down/j``
|
|
2. Saving the notebook: ``s``
|
|
3. Cell types: ``y``, ``m``, ``1-6``, ``t``
|
|
4. Cell creation: ``a``, ``b``
|
|
5. Cell editing: ``x``, ``c``, ``v``, ``d``, ``z``, ``shift+=``
|
|
6. Kernel operations: ``i``, ``.``
|
|
|
|
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Notebook%20Basics.ipynb>`__
|