GitHub - joouha/euporie: Jupyter notebooks in the terminal

|logo|

.. |logo| image:: https://raw.githubusercontent.com/joouha/euporie/refs/heads/dev/docs/_static/logo-magic.svg :alt:

####### euporie #######

.. content_start

Euporie is a terminal based interactive computing environment for Jupyter.

Euporie's apps allow you to interact with Jupyter kernels, and run Jupyter notebooks - entirely from the terminal.

If you're working with Jupyter notebooks in a terminal only environment, like an SSH server or a container, or just prefer working in the terminal, then euporie is the tool for you!

.. image:: https://github.com/joouha/euporie/assets/12154190/c8ea6e23-11bb-4ffc-a9e5-111f788c51ae :target: https://github.com/joouha/euporie/assets/12154190/c8ea6e23-11bb-4ffc-a9e5-111f788c51ae

.. list-table:: :align: center :widths: 25 25 25 25 :class: text-center

- Console <https://euporie.readthedocs.io/en/latest/packages/console.html>_
- Notebook <https://euporie.readthedocs.io/en/latest/packages/notebook.html>_
- Preview <https://euporie.readthedocs.io/en/latest/packages/preview.html>_
- Hub <https://euporie.readthedocs.io/en/latest/packages/hub.html>_

View more screenshots here <https://euporie.readthedocs.io/en/latest/pages/gallery.html>_

Try euporie

In your terminal - if you have uv <https://docs.astral.sh/uv/>_ installed, you can run any euporie app instantly without installing it, using uvx:

.. code-block:: console

$ uvx euporie notebook # launch the notebook editor $ uvx euporie notebook my.ipynb # ...optionally with a notebook to open $ uvx euporie console # interactive Jupyter console $ uvx euporie preview my.ipynb # render a notebook to the terminal

In your browser - no installation required: launch the live demo <https://euporie.readthedocs.io/en/latest/_static/lite.html>_.

If you'd rather install euporie permanently, see Install_ below.

Install

For day-to-day use, install euporie with uv <https://docs.astral.sh/uv/>_ (recommended), pipx <https://pipxproject.github.io/>_ or pip:

.. code-block:: console

$ uv tool install euporie $ # OR $ pipx install euporie $ # OR $ python -m pip install --user euporie

You can also run euporie without installing it - see Try euporie_ above.

Features

Edit and run notebooks in the terminal
Run code interactively in a console
Display images using terminal graphics (sixel / iterm / kitty)
Use Jupyter widgets interactively in the terminal
Render rich kernel output (markdown, tables, images, LaTeX, HTML, SVG, & PDF)
Tab-completion, line suggestions and contextual help
Convert a console session to a notebook
Micro / Vim / Emacs style key-bindings

Packages

Euporie is structured as a collection of packages, allowing you to install only the components you need:

euporie <https://euporie.readthedocs.io/>_ - Metapackage which installs all euporie apps and provides the euporie launcher command
euporie-core <https://euporie.readthedocs.io/en/latest/packages/euporie-core.html>_ - Core functionality shared across all apps (config system, kernel client, LSP client, shared widgets, and rich output rendering)
euporie-console <https://euporie.readthedocs.io/en/latest/packages/euporie-console.html>_ - Interactive console application
euporie-notebook <https://euporie.readthedocs.io/en/latest/packages/euporie-notebook.html>_ - Notebook editing application
euporie-preview <https://euporie.readthedocs.io/en/latest/packages/euporie-preview.html>_ - Notebook preview application
euporie-hub <https://euporie.readthedocs.io/en/latest/packages/euporie-hub.html>_ - Multi-user SSH server for euporie apps
apptk <https://euporie.readthedocs.io/en/latest/packages/apptk.html>_ - Terminal UI toolkit extending prompt_toolkit, used by euporie

Installing the euporie metapackage will pull in euporie-console, euporie-notebook, and euporie-preview. To install an individual app, install its package directly, e.g.:

.. code-block:: console

$ uv tool install euporie-notebook

Usage

Launcher

The euporie command acts as a launcher for the various euporie apps:

.. code-block:: console

  $ euporie notebook notebook.ipynb
  $ euporie console
  $ euporie preview notebook.ipynb
  $ euporie hub

If you don't want to install euporie, you can run any of these commands directly with uvx (e.g. uvx euporie notebook notebook.ipynb) - see Try euporie_.

Notebooks

You can edit a notebook using euporie-notebook, and passing the notebook's file path or URI as a command line argument:

.. code-block:: console

  $ euporie-notebook notebook.ipynb

Alternatively, launch euporie-notebook and open a notebook file by selecting "Open" from the file menu (Ctrl+O).

Console

To connect to a Jupyter kernel and run code interactively in a console session, you can run

.. code-block:: console

  $ euporie-console

(You can press Ctrl+Space to open the command palette in euporie-console).

Preview

To preview a notebook to the terminal, use the euporie-preview subcommand:

.. code-block:: console

  $ euporie-preview notebook.ipynb

Hub

To run euporie hub, a multi-user SSH server for euporie apps, run:

.. code-block:: console

  $ euporie-hub --port 8022 --host-keys=ssh_host_ed25519_key --client-keys=authorized_keys

where ssh_host_ed25519_key is the path to your host key file, and authorized_keys is a file containing SSH public keys allowed to connect.

Documentation

View the online documentation at: https://euporie.readthedocs.io/ <https://euporie.readthedocs.io/>_

The code is available on GitHub at: https://github.com/joouha/euporie <https://github.com/joouha/euporie>_

Development

Euporie is developed as a uv <https://docs.astral.sh/uv/>_ workspace mono-repo. The individual packages live under packages/. To set up a development environment:

.. code-block:: console

$ git clone https://github.com/joouha/euporie $ cd euporie $ uv sync

Compatibility

Euporie requires Python 3.10 or later. It works on Linux, Windows and MacOS

.. |PyPI| image:: https://img.shields.io/pypi/v/euporie.svg :target: https://pypi.python.org/project/euporie/ :alt: Latest Version

.. |RTD| image:: https://readthedocs.org/projects/euporie/badge/ :target: https://euporie.readthedocs.io/en/latest/ :alt: Documentation

.. |PyVer| image:: https://img.shields.io/pypi/pyversions/euporie :target: https://pypi.python.org/project/euporie/ :alt: Supported Python versions

.. |TryOnline| image:: https://img.shields.io/badge/try-online-red.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0xMjggLTEyOCAyNTYgMjU2Ij48ZGVmcz48Y2xpcFBhdGggaWQ9ImMiPjxjaXJjbGUgcj0iMTAwIi8+PC9jbGlwUGF0aD48L2RlZnM+PGNpcmNsZSByPSIxMDAiIGZpbGw9IiNkMDAiLz48ZyBmaWxsPSIjYzAwIiBjbGlwLXBhdGg9InVybCgjYykiPjxwYXRoIGQ9Im0gLTEwMCwtNjQgdiA0IEggMTAyIHYgLTQgeiBtIDAsMTQgdiA1IEggMTAyIHYgLTUgeiBtIDAsOSB2IDEwIEggMTAyIHYgLTEwIHogbSAwLDMwIHYgMTAgMTAgSCAxMDIgViAwIC0xMCBoIC0yMDIgeiBtIDAsMzUgdiAyNSBIIDEwMiB2IC0yNSB6IG0gMCw0MCB2IDUgSCAxMDIgdiAtNSB6IG0gMCwxMCBWIDgwIEggMTAyIHYgLTUgeiBtIDAsMTAgdiAzIEggMTAyIHYgLTMgaCAtMjAyIHoiLz48L2c+PGVsbGlwc2UgY3g9Ii00MCIgY3k9IjQ4IiByeD0iMjUiIHJ5PSIxNSIgZmlsbD0iI2MxMCIgc3Ryb2tlPSIjZDAwIiBzdHJva2Utd2lkdGg9IjUiLz48Y2lyY2xlIGN4PSI1MCIgcj0iMTciLz48Y2lyY2xlIGN4PSItODgiIGN5PSItODYiIHI9IjgiIGZpbGw9IiNlZWYiLz48Y2lyY2xlIGN4PSItOTMiIGN5PSI4NiIgcj0iNSIgZmlsbD0iI2Y4MCIvPjxwYXRoIGQ9Im0gOTIsLTEwOSAxMCwzMSAtMjYsLTE5IGggMzIgbCAtMjYsMTkgeiIgZmlsbD0iI2ZlMCIvPjwvc3ZnPg== :target: https://euporie.readthedocs.io/en/latest/_static/lite.html :alt: Try euporie online in your browser

.. |License| image:: https://img.shields.io/github/license/joouha/euporie?style=flat&color=purple :target: https://github.com/joouha/euporie/blob/main/LICENSE :alt: View license

.. |Stars| image:: https://img.shields.io/github/stars/joouha/euporie?style=flat&color=gold :target: https://github.com/joouha/euporie/stargazers :alt: ⭐