Welcome to Emacs IPython Notebook’s documentation!

Emacs IPython Notebook (EIN) provides fully featured IPython Notebook client and integrated REPL (like SLIME).

Highlighted features:

• Copy/paste cells, even to/from different notebooks.
• Console integration: You can easily connect to kernel via console application. This enables you to start debugging in the same kernel. It is even possible to connect console over ssh [1].
• IPython kernel can be “connected” to any buffers. This enables you to evaluate buffer/region using same kernel as notebook. Notebook goodies such as tooltip help, help browser and code completion are available in these buffers. [2]
• Jump to definition (go to the definition by hitting M-. over an object).

Other notebook features:

• Inline images
• Auto/manual-completion
• Popup (tooltip) help
• Syntax highlighting in each cell types (Python/Markdown/ReST/HTML)
• Help browser (opens when executing function?)
• Traceback viewer

Links:

• Repository at GitHub
• Issue Tracker at GitHub
• Online Documentation

[1]	You need to setup ein:notebook-console-args properly

[2]	Use the command ein:connect-to-notebook.

Quick try

This is a quick and clean way to try EIN separately from your Emacs setting. If you want to try EIN but think preparing all the requirements is too much, try this!:

git clone git://github.com/tkf/zeroein.git
zeroein/zeroein.py

This will launch a new Emacs instance. For more information, see:

zeroein/zeroein.py --help

Requirements

• IPython 0.12.1 (or developmental version): EIN won’t work with older versions.
• websocket.el
• (optional) mumamo: It will be automatically loaded when it is on the path. The official way to setup path is to load nXhtml.
• (optional) markdown-mode
• (optional) python-mode: It should work with either python.el or python-mode.el. Fabian Gallina’s python.el is required to use ein:notebook-console-open command.
• (optional) auto-complete.el You need to configure subpackage ein-ac to enable this feature.
• (optional) smartrep.el: This package enables you to omit typing prefix keys (e.g., C-c C-n C-n C-n ... instead of C-c C-n C-c C-n C-c C-n ...). You need to configure subpackage ein-smartrep to enable this feature.

Also, EIN heavily relies on standard Emacs libraries including EWOC and EIEIO. EIN is currently tested in Emacs 24.1.

Usage

1. Install module. Put Emacs lisp ein*.el files and Python file ein.py in your load path.

2. Require module:

   (require 'ein)

3. Start IPython notebook server.

4. Hit M-x ein:notebooklist-open to open notebook list.

Commands/Keybinds

Notebook list

You can start notebook by M-x ein:notebooklist-open and enter the port or URL of the IPython notebook server.

function (ein:notebooklist-open &optional url-or-port no-popup)

Open notebook list buffer.

function (ein:notebooklist-new-notebook &optional url-or-port callback cbargs)

Ask server to create a new notebook and open it in a new buffer.

function (ein:notebooklist-open-notebook-global nbpath)

Choose notebook from all opened notebook list and open it.

function ein:notebooklist-new-scratch-notebook

Open a notebook to try random thing.

Notebook

The following keybinds are available in notebook buffers.

C-c C-c ein:notebook-execute-current-cell

Execute cell at point.

C-c C-e ein:notebook-toggle-output-command

Toggle the visibility of the output of the cell at point. This does not alter the actual data stored in the cell.

C-c C-v ein:notebook-set-collapsed-all-command

Hide all cell output. When prefix is given, show all cell output.

C-c C-l ein:notebook-clear-output-command

Clear output from the current cell at point. Do not clear input prompt when the prefix argument is given.

C-c C-S-l ein:notebook-clear-all-output-command

Clear output from all cells. Do not clear input prompts when the prefix argument is given.

C-c C-k ein:notebook-kill-cell-command

Kill (“cut”) the cell at point. Note that the kill-ring for cells is not shared with the default kill-ring of Emacs (kill-ring for texts).

C-c M-w ein:notebook-copy-cell-command

Copy the cell at point. (Put the current cell into the kill-ring.)

C-c C-y ein:notebook-yank-cell-command

Insert (“paste”) the latest killed cell. Prefixes are act same as the normal yank command.

C-c C-a ein:notebook-insert-cell-above-command

Insert cell above. Insert markdown cell instead of code cell when the prefix argument is given.

C-c C-b ein:notebook-insert-cell-below-command

Insert cell below. Insert markdown cell instead of code cell when the prefix argument is given.

C-c C-t ein:notebook-toggle-cell-type

Toggle the cell type of the cell at point. Use ein:notebook-change-cell-type to change the cell type directly.

C-c C-u ein:notebook-change-cell-type

Change the cell type of the current cell. Prompt will appear in the minibuffer.

C-c C-s ein:notebook-split-cell-at-point

Split cell at current position. Newlines at the splitting point will be removed. This can be omitted by giving a prefix argument (C-u).

C-c RET ein:notebook-merge-cell-command

Merge next cell into current cell. If prefix is given, merge current cell into previous cell.

C-c C-n ein:notebook-goto-next-input-command

C-c C-p ein:notebook-goto-prev-input-command

C-c <up> ein:notebook-move-cell-up-command

C-c <down> ein:notebook-move-cell-down-command

C-c C-f ein:notebook-request-tool-tip-or-help-command

Show the help for the object at point using tooltip. When the prefix argument C-u is given, open the help in the pager buffer. You can explicitly specify the object by selecting it.

C-c TAB ein:notebook-complete-command

C-c C-x ein:notebook-view-traceback

Open traceback viewer for the traceback at point.

C-c C-r ein:notebook-restart-kernel-command

Send request to the server to restart kernel.

C-c C-z ein:notebook-kernel-interrupt-command

Interrupt the kernel. This is equivalent to do C-c in the console program.

C-c C-q ein:notebook-kill-kernel-then-close-command

Kill kernel and then kill notebook buffer. It does not kill buffer if killing kernel fails. To close notebook without killing kernel, just close the buffer as usual.

C-c C-o ein:notebook-console-open

Open IPython console. To use this function, ein:notebook-console-security-dir and ein:notebook-console-args must be set properly. This function requires Fabian Gallina’s python.el for now; It should be possible to support python-mode.el. Patches are welcome!

M-RET ein:notebook-execute-current-cell-and-goto-next

Execute cell at point and move to the next cell, or insert if none.

M-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

M-, ein:pytools-jump-back-command

Go back to the point where ein:pytools-jump-to-source-command is executed last time. When the prefix argument C-u is given, open the last point in the other window.

C-: ein:notebook-eval-string

Evaluate a code. Prompt will appear asking the code to run. This is handy when you want to execute something quickly without making a cell. If the code outputs something, it will go to the shared output buffer. You can open the buffer by the command ein:shared-output-pop-to-buffer.

C-x C-s ein:notebook-save-notebook-command

Save the notebook.

C-x C-w ein:notebook-rename-command

Rename current notebook and save it immediately.

NAME is any non-empty string that does not contain ‘/’ or ‘’.

function ein:notebook-delete-cell-command

Delete a cell. (WARNING: no undo!) This command has no key binding because there is no way to undo deletion. Use kill to play on the safe side.

If you really want use this command, you can do something like this (but be careful when using it!):

(define-key ein:notebook-mode-map "\C-c\C-d"
            'ein:notebook-delete-cell-command)

Connected buffer

You can connect any buffer (typically buffer opening Python file) to opened notebook and use the kernel of the notebook to execute the code, inspect objects, auto-complete code, jump to the other source, etc. Once the buffer is connected to the notebook, minor mode ein:connect-mode is enabled and the following keybinds are available.

C-c C-c ein:connect-run-or-eval-buffer

Run buffer using the %run magic command or eval whole buffer if the prefix C-u is given. Variable ein:connect-run-command sets the command to run. You can change the command and/or set the options. See also: ein:connect-run-buffer, ein:connect-eval-buffer.

C-c C-r ein:connect-eval-region

C-c C-f ein:connect-request-tool-tip-or-help-command

C-c TAB ein:connect-complete-command

C-c C-z ein:connect-pop-to-notebook

C-: ein:connect-eval-string

M-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

M-, ein:pytools-jump-back-command

Go back to the point where ein:pytools-jump-to-source-command is executed last time. When the prefix argument C-u is given, open the last point in the other window.

Other useful commands:

function (ein:connect-to-notebook buffer-or-name)

Connect any buffer to notebook and its kernel.

function ein:connect-eval-buffer

Evaluate the whole buffer. Note that this will run the code inside the if __name__ == "__main__": block.

function (ein:connect-run-buffer &optional ask-command)

Run buffer using %run. Ask for command if the prefix C-u is given. Variable ein:connect-run-command sets the default command.

Shared output buffer

function ein:shared-output-pop-to-buffer

Open shared output buffer.

Keymap for ein:shared-output-mode.

M-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

Traceback viewer

Traceback in notebook buffer is not easy to understand. You can open Traceback viewer by the command ein:notebook-view-traceback. In the Traceback viewer, following keybinds are available.

Keymap for ein:traceback-mode.

RET ein:tb-jump-to-source-at-point-command

p ein:tb-prev-item

n ein:tb-next-item

q bury-buffer

PyTools

These commands can be used in the notebook buffer and the connected buffer.

function ein:pytools-whos

Execute %whos magic command and popup the result.

function (ein:pytools-hierarchy &optional ask)

Draw inheritance graph of the class at point. hierarchymagic extension is needed to be installed. You can explicitly specify the object by selecting it.

Customization

You can customize EIN using the Emacs customization UI by typing M-x customize-group RET ein RET. All the configurable variables are listed below.

Subpackages

variable ein:use-auto-complete

Set to t to use preset auto-complete configuration.

variable ein:use-auto-complete-superpack

Set to t to use preset a little bit hacky auto-complete configuration.

variable ein:use-smartrep

Set to t to use preset smartrep configuration.

variable ein:load-dev

Load development helper.

Notebook list

variable ein:url-or-port

List of default url-or-port values. This will be used for completion. So put your IPython servers. You can connect to servers not in this list (but you will need to type every time).

variable ein:scratch-notebook-name-template

Template of notebook name. This value is used from ein:notebooklist-new-scratch-notebook.

Notebook

variable ein:notebook-discard-output-on-save

Configure if the output part of the cell should be saved or not.

no : symbol

Save output. This is the default.

yes : symbol

Always discard output.

a function

This function takes two arguments, notebook and cell. Return t to discard output and return nil to save. For example, if you don’t want to save image output but other kind of output, use ein:notebook-cell-has-image-output-p.

Note that using function needs EIN lisp API, which is not defined yet. So be careful when using EIN functions. They may change.

variable ein:notebook-modes

Notebook modes to use (in order of preference).

When the notebook is opened, mode in this value is checked one by one and the first usable mode is used. By default, MuMaMo is used when it is installed. If not, a simple mode derived from python-mode is used.

Examples:

Avoid using MuMaMo even when it is installed:

(setq ein:notebook-modes (delq 'ein:notebook-mumamo-mode ein:notebook-modes))

Do not use python-mode. Use plain mode when MuMaMo is not installed:

(setq ein:notebook-modes '(ein:notebook-mumamo-mode ein:notebook-plain-mode))

variable ein:notebook-kill-buffer-ask

Whether EIN should ask before killing unsaved notebook buffer.

variable ein:notebook-console-security-dir

Security directory setting.

Following types are valid:

string

Use this value as a path to security directory. Handy when you have only one IPython server.

alist

An alist whose element is “(URL-OR-PORT . DIR)”. Key (URL-OR-PORT) can be string (URL), integer (port), or default (symbol). The value of default is used when other key does not much. Normally you should have this entry.

function

Called with an argument URL-OR-PORT (integer or string). You can have complex setting using this.

variable ein:notebook-console-executable

IPython executable used for console.

Example: "/user/bin/ipython". Types same as ein:notebook-console-security-dir are valid.

variable ein:notebook-console-args

Additional argument when using console.

Example: "--ssh HOSTNAME". Types same as ein:notebook-console-security-dir are valid.

variable ein:cell-traceback-level

Number of traceback stack to show. Hidden tracebacks are not discarded. You can always view them using the command ein:notebook-view-traceback.

Connect

variable ein:connect-run-command

%run magic command used for ein:connect-run-buffer. Types same as ein:notebook-console-security-dir are valid.

variable ein:connect-save-before-run

Whether the buffer should be saved before ein:connect-run-buffer.

variable ein:propagate-connect

Set to t to connect to the notebook after jumping to a buffer.

MuMaMo

variable ein:mumamo-codecell-mode

Major Mode for Code Cell.

variable ein:mumamo-textcell-mode

Major Mode for Text Cell.

variable ein:mumamo-htmlcell-mode

Major Mode for HTML Cell.

variable ein:mumamo-markdowncell-mode

Major Mode for Markdown Cell.

variable ein:mumamo-rawcell-mode

Major Mode for Raw Cell.

variable ein:mumamo-headingcell-mode

Major Mode for Heading Cell.

variable ein:mumamo-fallback-mode

Fallback Major Mode.

Misc

variable ein:query-timeout

Default query timeout for HTTP access in millisecond.

Indices and tables

• Index
• Search Page