Installation

Euporie is on pypi, so can be installed like any other Python package.

To install euporie globally, use the following:

$ uv tool install euporie

$ pipx install euporie

$ pip install euporie

If you want to try the latest and potentially unstable unreleased changes, you can install euporie from git:

$ uv tool install git+https://github.com/joouha/euporie.git@dev

$ pipx install git+https://github.com/joouha/euporie.git@dev

$ pip install git+https://github.com/joouha/euporie.git@dev

Note

Although euporie does not have any compiled components, some of its dependencies may require compilation as part of their build process, depending on the availability of binary wheels. If this is the case, you may need to install the relevant build dependencies for your distribution, such as python-dev and gcc or equivalent.

Try without installing

You can use uv or pipx to try euporie without installing it:

$ uvx euporie notebook

$ pipx run --spec 'euporie[all]' euporie notebook

You can also try euporie online here:

https://mybinder.org/v2/gh/joouha/euporie-binder/HEAD?urlpath=%2Feuporie%2F

Jupyter Kernels

Euporie uses Jupyter kernels to execute code in notebooks. If you see a “no kernels found” error when trying to run a notebook, you’ll need to ensure you have the appropriate kernel installed and registered.

For Python notebooks, install and register the IPython kernel:

To install ipykernel in a virtual environment:

$ uv pip install ipykernel
$ uv run python -m ipykernel install --user

To install ipykernel for the current user:

$ pip install --user ipykernel
$ python -m ipykernel install --user

For other programming languages, you’ll need to install the appropriate kernel package.

You can view a list of available kernel implementations for various programming languages here.

Optional Dependencies

Euporie supports a wide range of rendering methods in order to get your notebooks looking as nice as possible in the terminal. The following section lists the various rendering methods available, and details what needs to be installed for them to be used.

Images

Euporie will attempt to render images in the best possible way it can.

Note

timg is installed as a dependency of euporie and is used to render images as sixels or ansi art. However, euporie will preferentially use an external application if it is installed and is more performant or gives higher quality output.

The following methods will be used if they are available:

Kitty’s Terminal Graphics Protocol

If your terminal supports kitty’s terminal graphics protocol, euporie will use it to render images.

This is supported by kitty, WezTerm, and Konsole.

You can manually this protocol by launching euporie with the --graphics kitty flag.

iTerm2’s Terminal Graphics Protocol

If you’re using iTerm2, euporie can use its proprietary graphics protocol to render images.

You can select this protocol by launching euporie with the --graphics iterm flag.

Sixels

If supported by your terminal, euporie can show graphical images in cell outputs using the Sixel graphics protocol.

You can select this protocol by launching euporie with the --graphics sixel flag.

This requires one of the following dependencies:

Ansi Art

If all else fails, euporie will fall back to using ansi art to display images.

You can select this protocol by launching euporie with the --graphics none flag.

Warning

If a graphics protocol is manually selected but the terminal is not known to support it, it will not be used. To force the use of a manually selected graphic protocol, launch euporie with the --force-graphics flag. This may lead to unexpected behaviours and broken terminal output!

SVG

Euporie can display SVG output by first rasterizing it, for which one of the following is required:

  • Python packages

    • cairosvg

  • External applications

PDF

Euporie can display the first page of PDF files using one of the following:

Note

Currently only the first page of PDF files can be displayed.

HTML

Euporie includes its own custom HTML renderer, which it uses to render HTML outputs, meaning that external programs are not longer required to display HTML.

If HTML rendering fails for some reason, euporie will fall back on one of the following for rendering HTML:

Note

mtable will only render HTML tables in cell outputs, so is useful if you are working with dataframes

LaTeX

Euporie will render LaTeX in markdown and cell outputs using terminal graphics or unicode text, using any of the following if they are installed:

  • Python packages

    • pylatexenc

    • ipython

  • External applications

    • dvipng

Note

flatlatex is a dependency of euporie, so will be installed by default