Jupyter and IPython 2.x/3.x notebook client in Emacs
Jupyter Notebook Emacs Lisp Other
Latest commit 3412470 Jan 19, 2017 @millejoh More convenience finding the channels debug buffer
Post Ipython 2.0 there are no longer separate websocket connections for iopub
and shell, they now share the same websocket connect. This is a simple
convenience function for finding the websocket log buffer for the new-style
connection.
Permalink
Failed to load latest commit information.
.idea Merge remote-tracking branch 'refs/remotes/origin/master' into org-babel Oct 15, 2016
.ipynb_checkpoints Cleanup, documenting options for inline Latex images Apr 12, 2016
AltairTutorial Merge remote-tracking branch 'refs/remotes/origin/master' into org-babel Oct 15, 2016
doc Actually write a correct example for using the :image header. Jan 18, 2017
lisp More convenience finding the channels debug buffer Jan 19, 2017
log Travis fails if there is no log directory. Dec 18, 2016
ltxpng Merge remote-tracking branch 'refs/remotes/origin/master' into org-babel Oct 15, 2016
tests Desperate attempts to fix default coding when running testein. Dec 19, 2016
tools Desperate attempts to fix default coding when running testein. Dec 19, 2016
.buildinfo Demo notebook for generating screenshots. May 19, 2015
.gitignore Travis fails if there is no log directory. Dec 18, 2016
.travis.yml Testein and cask working together, maybe. Dec 18, 2016
CONTRIBUTING.md point URI references to millejoh. May 16, 2015
COPYING Squashed 'lib/request/' content from commit 1245013 Sep 24, 2016
Cask Version bump, integrate docs into Cask, new doc theme. Jan 17, 2017
Demo.ipynb Cleanup, documenting options for inline Latex images Apr 12, 2016
Development Ideas.ipynb Updating notebook formats, .gitignore additions. Jan 6, 2016
Enhancements.org Merge branch 'master' into 38-fixing-testing Sep 24, 2016
Makefile Cleanup Apr 22, 2016
README.rst Fixes for README. Dec 23, 2016
pavement.py Preliminary update and test commands Sep 24, 2016

README.rst

EIN -- Emacs IPython Notebook Build Status MELPA development version MELPA stable version

--- or EIN Is not only for Notebooks.

EIN works with IPython 2.x, 3.x, and Jupyter! Note that remote and password protected logins are working with IPython 3.x, but have not been tested with Jupyter.

Note

The code has been stable enough for my day to day work, but there are no guarantees for the safety for your notebook data. Please make sure that you back-up and back-up often!

Note

The code for testing EIN is horribly broken, but I regularly hand check the code running against IPython's suite of sample notebooks. It's a worse-is-better solution to problem requiring a time-consuming solution.

Org-mode Integration

EIN now integrates with org-mode! The code was heavily inspired by ob-ipython which is another project very much worth checking out. Find it on MELPA.

Screenshots

Plotting in Emacs IPython Notebook
EIN connecting to an R kernel

See more!

Features

The Emacs IPython Notebook (EIN) provides a client for IPython v2.x and 3.x and Jupyter notebooks via an integrated REPL (like SLIME) in Emacs. EIN makes notebook editing very powerful by allowing you to use Emacs features; it also expose IPython features such as code evaluation, object inspection and code completion to the Emacs side. These features can be accessed anywhere in Emacs and improve Python code editing and reading in Emacs.

Highlighted features:

  • Copy/paste cells, even to/from different notebooks.
  • Console integration: You can easily connect to a kernel via the console application. This enables you to start debugging in the same kernel. It is even possible to connect to a console over ssh.
  • An IPython kernel can be "connected" to any buffer. This enables you to evaluate a buffer or buffer region using the same kernel as the notebook. Notebook goodies such as tooltip help, help browser and code completion are available in these buffers.
  • 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 type (Python/Markdown)
  • Help browser (opens when executing function?)
  • Traceback viewer
  • Integration with org-mode
  • Support for debugging via %debug
  • Multiple python kernels
  • EXPERIMENTAL: Non-python kernels! R runs in EIN, see the screenshot above!

Links:

Quick try

Install from MELPA! Seriously, installing from MELPA is the easiest way to ensure all of ein's dependencies are correctly installed. zeroein.el is from a bygone era and does not quite work the way it used to. If you are determined, and slightly masochistic, you can attempt the following:

git clone git://github.com/millejoh/emacs-ipython-notebook.git
cd emacs-ipython-notebook/
lisp/zeroein.el

This will launch a new Emacs instance.

You can use environment variable EMACS to control Emacs executable to use.:

EMACS=emacs-snapshot lisp/zeroein.el

The above command requires /bin/sh. If the above command does not work (e.g., you are using MS Windows), try the following command:

emacs -Q -l lisp/zeroein.el

Requirements

  • IPython 2.0 or higher or current versions of Jupyter

  • Tornado 4.0.2 or higher.

  • websocket.el 1.3

  • request.el >= 0.2

  • (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: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.

  • (optional) jedi.el: Python auto-completion for emacs using jedi. In your emacs initialization file add

    (add-hook 'ein:connect-mode-hook 'ein:jedi-setup)

Also, EIN heavily relies on standard Emacs libraries including EWOC, EIEIO and json.el. EIN is currently tested against Emacs 23.3 and 24.3. It is known to work in Emacs 23.2, 24.x, 25.1, and development version (26.0.x).

Usage

  1. Install from MELPA. Put Emacs lisp ein*.el files and Python file ein.py in your load path. See online documentation for more information.
  2. Start the Jupyter notebook server.
  3. (Optional) Newer versions of Jupyter have token authentication enabled by default so you will need to call M-x ein:notebooklist-login and enter the token as the password.
  4. Execute M-x ein:notebooklist-open to open notebook list.

Subpackages

Enable auto-complete.el:

(setq ein:use-auto-complete t)
;; Or, to enable "superpack" (a little bit hacky improvements):
;; (setq ein:use-auto-complete-superpack t)

Enable smartrep.el:

(setq ein:use-smartrep t)

Keybindings - Notebook

key             binding
---             -------

C-c             Prefix Command
C-x             Prefix Command
ESC             Prefix Command
.               ein:notebook-complete-dot
C-:             ein:shared-output-eval-string
<C-down>        ein:worksheet-goto-next-input
<C-up>          ein:worksheet-goto-prev-input
<M-S-return>    ein:worksheet-execute-cell-and-insert-below
<M-down>        ein:worksheet-move-cell-down
<M-up>          ein:worksheet-move-cell-up

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

M-RET           ein:worksheet-execute-cell-and-goto-next
M-,             ein:pytools-jump-back-command
M-.             ein:pytools-jump-to-source-command
M-n             ein:worksheet-next-input-history
M-p             ein:worksheet-previous-input-history

C-c C-a         ein:worksheet-insert-cell-above
C-c C-b         ein:worksheet-insert-cell-below
C-c C-c         ein:worksheet-execute-cell
C-c C-e         ein:worksheet-toggle-output
C-c C-f         ein:pytools-request-tooltip-or-help
C-c TAB         ein:completer-complete
C-c C-k         ein:worksheet-kill-cell
C-c C-l         ein:worksheet-clear-output
C-c RET         ein:worksheet-merge-cell
C-c C-n         ein:worksheet-goto-next-input
C-c C-o         ein:console-open
C-c C-p         ein:worksheet-goto-prev-input
C-c C-q         ein:notebook-kill-kernel-then-close-command
C-c C-r         ein:notebook-restart-kernel-command
C-c C-s         ein:worksheet-split-cell-at-point
C-c C-t         ein:worksheet-toggle-cell-type
C-c C-u         ein:worksheet-change-cell-type
C-c C-v         ein:worksheet-set-output-visibility-all
C-c C-w         ein:worksheet-copy-cell
C-c C-x         ein:tb-show
C-c C-y         ein:worksheet-yank-cell
C-c C-z         ein:notebook-kernel-interrupt-command
C-c ESC         Prefix Command
C-c !           ein:worksheet-rename-sheet
C-c +           ein:notebook-worksheet-insert-next
C-c -           ein:notebook-worksheet-delete
C-c 1           ein:notebook-worksheet-open-1th
C-c 2           ein:notebook-worksheet-open-2th
C-c 3           ein:notebook-worksheet-open-3th
C-c 4           ein:notebook-worksheet-open-4th
C-c 5           ein:notebook-worksheet-open-5th
C-c 6           ein:notebook-worksheet-open-6th
C-c 7           ein:notebook-worksheet-open-7th
C-c 8           ein:notebook-worksheet-open-8th
C-c 9           ein:notebook-worksheet-open-last
C-c {           ein:notebook-worksheet-open-prev-or-last
C-c }           ein:notebook-worksheet-open-next-or-first
C-c C-S-l       ein:worksheet-clear-all-output
C-c C-#         ein:notebook-close
C-c C-'         ein:worksheet-turn-on-autoexec
C-c C-,         ein:pytools-jump-back-command
C-c C-.         ein:pytools-jump-to-source-command
C-c C-/         ein:notebook-scratchsheet-open
C-c C-;         ein:shared-output-show-code-cell-at-point
C-c <down>      ein:worksheet-move-cell-down
C-c <up>        ein:worksheet-move-cell-up

C-c M-+         ein:notebook-worksheet-insert-prev
C-c M-w         ein:worksheet-copy-cell
C-c M-{         ein:notebook-worksheet-move-prev
C-c M-}         ein:notebook-worksheet-move-next

Keybindings - Connect

In Python (or any other) buffer, you can connect to any open notebook by M-x ein:connect-to-notebook then choose appropriate notebook. After connecting to the notebook (and hence its kernel), the following commands are available.

key             binding
---             -------

C-c             Prefix Command
ESC             Prefix Command
.               ein:completer-dot-complete
C-:             ein:shared-output-eval-string

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

C-c C-a         ein:connect-toggle-autoexec
C-c C-c         ein:connect-run-or-eval-buffer
C-c C-f         ein:pytools-request-tooltip-or-help
C-c TAB         ein:completer-complete
C-c C-l         ein:connect-reload-buffer
C-c C-o         ein:console-open
C-c C-r         ein:connect-eval-region
C-c C-x         ein:tb-show
C-c C-z         ein:connect-pop-to-notebook
C-c C-,         ein:pytools-jump-back-command
C-c C-.         ein:pytools-jump-to-source-command
C-c C-/         ein:notebook-scratchsheet-open

License

Emacs IPython Notebook is licensed under GPL v3. See COPYING for details.