EIN -- Emacs IPython Notebook

Emacs IPython Notebook (EIN), despite its name, is a jupyter client for all languages. It does not work under non-WSL Windows environments.

No require statements, e.g. (require 'ein), are necessary, contrary to the prevailing documentation, which should be disregarded.

Org users please find ob-ein, a jupyter Babel backend.

AWS GCE (Preview) integration is in alpha.

EIN was originally written by [tkf]. A jupyter Babel backend was first introduced by [gregsexton].

Install

As described in Getting started, ensure melpa's whereabouts in init.el or .emacs:

(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/"))

Then

M-x package-refresh-contents RET
M-x package-install RET ein RET

Alternatively, directly clone this repo and make install.

Usage

Start EIN using ONE of the following:

Open an .ipynb file, press C-c C-o, or,
M-x ein:run launches a jupyter process from emacs, or,
M-x ein:login to a running jupyter server, or,
[Jupyterhub] M-x ein:login to any of
- https://hub.data8x.berkeley.edu
- https://hub.data8x.berkeley.edu/user/1dcdab3
- https://hub.data8x.berkeley.edu/user/1dcdab3/?token=c421c68, or,
[Preview] To run on AWS or GCE, open an .ipynb file, press C-c C-r. See AWS GCE (Preview).

M-x ein:stop prompts to halt local and remote jupyter services.

Alternatively, ob-ein.

FAQ

How do I...

... report a bug?

Note EIN is tested only for released GNU Emacs versions 25.1 and later. Pre-release versions will not work.

First try emacs -Q -f package-initialize --eval "(setq debug-on-error t)" and reproduce the bug. The -Q skips any user configuration that might interfere with EIN.

Then file an issue using M-x ein:dev-bug-report-template.

... display images inline?

We find inserting images into emacs disruptive, and so default to spawning an external viewer. To override this,

M-x customize-group RET ein
Ein:Output Area Inlined Images

... configure the external image viewer?

M-x customize-group RET mailcap
Mailcap User Mime Data

On a typical Linux system, one might configure a viewer for MIME Type image/png as a shell command convert %s -background white -alpha remove -alpha off - | display -immutable.

... get IDE-like behavior?

The official python module for EIN is elpy, installed separately. Other program modes for non-python kernels may be installed with varying degrees of EIN compatibility.

... render LaTeX?

The official LaTeX module for EIN is math-preview, installed separately.

... send expressions from a python buffer to a running kernel?

Unpublicized keybindings exclusively for the Python language C-c C-/ e and C-c C-/ r send the current statement or region respectively to a running kernel. If the region is not set, C-c C-/ r sends the entire buffer. You must manually inspect the *ein:shared output* buffer for errors.

ob-ein

Configuration:

M-x customize-group RET org-babel
Org Babel Load Languages:
  Insert (ein . t)
  For example, '((emacs-lisp . t) (ein . t))

Snippet:

#+BEGIN_SRC ein-python :session localhost
  import numpy, math, matplotlib.pyplot as plt
  %matplotlib inline
  x = numpy.linspace(0, 2*math.pi)
  plt.plot(x, numpy.sin(x))
#+END_SRC

The :session is the notebook url, e.g., http://localhost:8888/my.ipynb, or simply localhost, in which case org evaluates anonymously. A port may also be specified, e.g., localhost:8889.

Language can be ein-python, ein-r, or ein-julia. The relevant jupyter kernel must be installed before use. Additional languages can be configured via:

M-x customize-group RET ein
Ob Ein Languages

AWS GCE (Preview)

M-x customize-option RET ein:gat-vendor

From a notebook or raw ipynb buffer, M-x ein:gat-run-remote opens the notebook on an AWS spot or GCE preemptible instance. You must M-x ein:stop or exit emacs to stop incurring charges!

M-x ein:gat-run-remote-batch runs the notebook in batch mode.

Results appear in the run-remote directory.

See dickmao/Kaggler for examples of importing Kaggle datasets.

See gat usage for information about the gat utility.

Keymap (C-h m)

Key             Binding
-------------------------------------------------------------------------------
C-<down>     ein:worksheet-goto-next-input-km
C-<up>               ein:worksheet-goto-prev-input-km
M-S-<return> ein:worksheet-execute-cell-and-insert-below-km
M-<down>     ein:worksheet-not-move-cell-down-km
M-<up>               ein:worksheet-not-move-cell-up-km

C-x C-s              ein:notebook-save-notebook-command-km
C-x C-w              ein:notebook-rename-command-km

M-RET                ein:worksheet-execute-cell-and-goto-next-km
M-,          ein:pytools-jump-back-command
M-.          ein:pytools-jump-to-source-command

C-c C-a              ein:worksheet-insert-cell-above-km
C-c C-b              ein:worksheet-insert-cell-below-km
C-c C-c              ein:worksheet-execute-cell-km
C-u C-c C-c                  ein:worksheet-execute-all-cells
C-c C-e              ein:worksheet-toggle-output-km
C-c C-f              ein:file-open-km
C-c C-k              ein:worksheet-kill-cell-km
C-c C-l              ein:worksheet-clear-output-km
C-c RET              ein:worksheet-merge-cell-km
C-c C-n              ein:worksheet-goto-next-input-km
C-c C-o              ein:notebook-open-km
C-c C-p              ein:worksheet-goto-prev-input-km
C-c C-q              ein:notebook-kill-kernel-then-close-command-km
C-c C-r              ein:notebook-reconnect-session-command-km
C-c C-s              ein:worksheet-split-cell-at-point-km
C-c C-t              ein:worksheet-toggle-cell-type-km
C-c C-u              ein:worksheet-change-cell-type-km
C-c C-v              ein:worksheet-set-output-visibility-all-km
C-c C-w              ein:worksheet-copy-cell-km
C-c C-y              ein:worksheet-yank-cell-km
C-c C-z              ein:notebook-kernel-interrupt-command-km
C-c C-S-l    ein:worksheet-clear-all-output-km
C-c C-#              ein:notebook-close-km
C-c C-$              ein:tb-show-km
C-c C-/              ein:notebook-scratchsheet-open-km
C-c C-;              ein:shared-output-show-code-cell-at-point-km
C-c <down>   ein:worksheet-move-cell-down-km
C-c <up>     ein:worksheet-move-cell-up-km

C-c C-x C-r  ein:notebook-restart-session-command-km

C-c M-w              ein:worksheet-copy-cell-km

yatsky / emacs-ipython-notebook