Configuration

Configuring Euporie

Euporie has a range of configurable options which affect euporie’s behaviour and appearance.

Options are validated at application startup, so if an option is set to an invalid value, it will be ignored.

The options can be set in three different ways:

Command Line Arguments

Euporie can be configured by passing flags (and sometimes values) on the command line when euporie is launched. The flags for each configuration option and the allowed values are listed in Configuration Options.

$ euporie --color-scheme=light --no-show-cell-borders --expand notebook.ipynb

Optionals set on the command line are not persisted, and only apply to the application which is being run.

Options set on the command line will override those set via an environment variable, in the configuration file, and the default values.

Environment Variables

Euporie can be configured by setting environment variables. Each option can be set by assigning a value to an environment variable with uppercase option name, prefixed with EUPORIE_ for global configuration settings.

To set a configuration option for an individual app, the environment variable should additionally be prefixed with the app’s name: as EUPORIE_NOTEBOOK_, EUPORIE_CONSOLE_, EUPORIE_PREVIEW_, or EUPORIE_HUB_ .

The global version of each configuration option’s environment variable are listed in Configuration Options.

Example

$ EUPORIE_COLOR_SCHEME=light EUPORIE_SHOW_CELL_BORDERS=False EUPORIE_EXPAND=True euporie-notebook notebook.ipynb

Setting boolean values to an empty string will cause them to evaluate to False.

Options set in via an environment variable will override those set in the configuration file and the default values.

Configuration File

Euporie can be configured using a JSON configuration file. The file takes the form of key: value pairs, where the key is one of the options listed in Configuration Options.

Settings can be applied to an individual application be specifying them under that application’s name.

Warning

The configuration file is read when euporie is launched, and modifying options from the Settings menu in euporie will cause the configuration file to be updated. Thus, any changes made to the configuration file while euporie is running may be lost, so this is not recommended.

Example

{
  "color_scheme": "light",
  "syntax_theme": "native",
  "notebook": {
    "expand": false,
    "always_show_tab_bar": true,
    "show_cell_borders": false
  },
  "console": {
    "color_scheme": "default",
    "syntax_theme": "dracula"
  },
  "preview": {
    "show_cell_borders": true
  }
}

File Location

The location of Euporie’s configuration file depends on your operating system:

Linux	`$XDG_CONFIG_HOME/euporie/config.json`
Mac OS	`~/Library/Application Support/<euporie>/config.json`
Windows	`%APPDATA%\Local\euporie\config.json`

If the file cannot be parsed as valid JSON, the file will be ignored.

Options set in the configuration file will override the default values.

Configuration Options

All available configuration options are listed below:

version

flags

--version or -V

default

False

type

boolean

description

Show the version number and exit

If set, euporie will print the current version number of the application and exit. All other configuration options will be ignored.

Note

This cannot be set in the configuration file or via an environment variable

log_file

flags

--log-file

environment variable

EUPORIE_LOG_FILE

default

''

type

string

description

File path for logs

When set to a file path, the log output will be written to the given path. If no value is given output will be sent to the standard output.

log_level

flags

--log-level

environment variable

EUPORIE_LOG_LEVEL

default

'warning'

type

string

options

['debug', 'info', 'warning', 'error', 'critical']

description

Set the log level

When set, logging events at the given level are emitted.

log_config

flags

--log-config

environment variable

EUPORIE_LOG_CONFIG

type

string

description

Additional logging configuration

A JSON string specifying additional logging configuration.

clipboard

flags

--clipboard

environment variable

EUPORIE_CLIPBOARD

default

'external'

type

string

options

['external', 'internal', 'terminal']

description

The preferred clipboard access method

The clipboard access method to use. - external: Data is saved to the system clipboard using OS native tooling. - internal: Clipboard data is only stored and usable inside euporie - it is

not saved to the system clipboard.

terminal: uses OSC52 escape sequences to retrieve and set the clipboard
contents. Requires your terminal emulator to support OSC52. Works over SSH.

show_shadows

flags

--show-shadows

environment variable

EUPORIE_SHOW_SHADOWS

default

True

type

boolean

description

Show or hide shadows under menus and dialogs

Sets whether shadows are shown under dialogs and popup-menus.

set_cursor_shape

flags

--set-cursor-shape

environment variable

EUPORIE_SET_CURSOR_SHAPE

default

True

type

boolean

description

Whether to set the shape of the cursor depending on the editing mode

When set to True, the euporie will set the shape of the terminal’s cursor to a beam in insert mode and and underline in replace mode when editing.

cursor_blink

flags

--cursor-blink

environment variable

EUPORIE_CURSOR_BLINK

default

False

type

boolean

description

Whether to blink the cursor

When set to True, the cursor will blink.

files

environment variable

EUPORIE_FILES

default

[]

type

array

description

List of file names to open

A list of file paths to open when euporie is launched.

edit_mode

flags

--edit-mode

environment variable

EUPORIE_EDIT_MODE

default

'micro'

type

string

options

['micro', 'emacs', 'vi']

description

Key-binding mode for text editing

Key binding style to use when editing cells.

tab_size

flags

--tab-size

environment variable

EUPORIE_TAB_SIZE

default

4

type

integer

description

Spaces per indentation level

The number of spaces to use per indentation level. Should be set to 4.

terminal_polling_interval

flags

--terminal-polling-interval

environment variable

EUPORIE_TERMINAL_POLLING_INTERVAL

default

0

type

integer

description

Time between terminal colour queries

Determine how frequently the terminal should be polled for changes to the background / foreground colours. Set to zero to disable terminal polling.

autoformat

flags

--autoformat

environment variable

EUPORIE_AUTOFORMAT

default

False

type

boolean

description

Automatically re-format code cells when run

Whether to automatically reformat code cells before they are run.

format_black

flags

--format-black

environment variable

EUPORIE_FORMAT_BLACK

default

True

type

boolean

description

Use black when re-formatting code cells

Whether to use black when reformatting code cells.

format_isort

flags

--format-isort

environment variable

EUPORIE_FORMAT_ISORT

default

True

type

boolean

description

Use isort when re-formatting code cells

Whether to use isort when reformatting code cells.

format_ssort

flags

--format-ssort

environment variable

EUPORIE_FORMAT_SSORT

default

True

type

boolean

description

Use ssort when re-formatting code cells

Whether to use ssort when reformatting code cells.

syntax_theme

flags

--syntax-theme

environment variable

EUPORIE_SYNTAX_THEME

default

'euporie'

type

string

description

Syntax highlighting theme

The name of the pygments style to use for syntax highlighting.

color_depth

flags

--color-depth

environment variable

EUPORIE_COLOR_DEPTH

type

integer

options

[1, 4, 8, 24]

description

The color depth to use

The number of bits to use to represent colors displayable on the screen. If set to None, the supported color depth of the terminal will be detected automatically.

tmux_graphics

flags

--tmux-graphics

environment variable

EUPORIE_TMUX_GRAPHICS

default

False

type

boolean

description

Enable terminal graphics in tmux (experimental)

If set, terminal graphics will be used if tmux is running by performing terminal escape sequence pass-through. You must restart euporie for this to take effect.

You will also need to ensure that allow-passthrough is set to on in your tmux configuration.

Warning

Terminal graphics in tmux is experimental, and is not guaranteed to work. Use at your own risk!

color_scheme

flags

--color-scheme

environment variable

EUPORIE_COLOR_SCHEME

default

'default'

type

string

options

['default', 'inverse', 'light', 'dark', 'black', 'white', 'custom']

description

The color scheme to use

The color scheme to use: auto means euporie will try to use your terminal’s color scheme, light means black text on a white background, and dark means white text on a black background.

custom_background_color

flags

--custom-background-color or --custom-bg-color or --bg

environment variable

EUPORIE_CUSTOM_BACKGROUND_COLOR

default

''

type

string

description

Background color for “Custom” color theme

The hex code of the color to use for the background in the “Custom” color scheme.

custom_foreground_color

flags

--custom-foreground-color or --custom-fg-color or --fg

environment variable

EUPORIE_CUSTOM_FOREGROUND_COLOR

default

''

type

string

description

Foreground color for “Custom” color theme

The hex code of the color to use for the foreground in the “Custom” color scheme.

accent_color

flags

--accent-color

environment variable

EUPORIE_ACCENT_COLOR

default

'ansiblue'

type

string

description

Accent color to use in the app

The hex code of a color to use for the accent color in the application.

key_bindings

flags

--key-bindings

environment variable

EUPORIE_KEY_BINDINGS

default

{}

type

object

description

Additional key binding definitions

A mapping of component names to mappings of command name to key-binding lists.

graphics

flags

--graphics

environment variable

EUPORIE_GRAPHICS

type

string

options

['none', 'sixel', 'kitty', 'iterm']

description

The preferred graphics protocol

The graphics protocol to use, if supported by the terminal. If set to “none”, terminal graphics will not be used.

wrap_cell_outputs

flags

--wrap-cell-outputs

environment variable

EUPORIE_WRAP_CELL_OUTPUTS

default

False

type

boolean

description

Wrap cell output text.

Whether text-based cell outputs should be wrapped.

kernel_name

flags

--kernel-name or --kernel

environment variable

EUPORIE_KERNEL_NAME

default

'python3'

type

string

description

The name of the kernel to start by default

The name of the kernel selected automatically by the console app or in new notebooks. If set to an empty string, the user will be asked which kernel to launch.

record_cell_timing

flags

--record-cell-timing

environment variable

EUPORIE_RECORD_CELL_TIMING

default

False

type

boolean

description

Should timing data be recorded in cell metadata.

When set, execution timing data will be recorded in cell metadata.

line_numbers

flags

--line-numbers

environment variable

EUPORIE_LINE_NUMBERS

default

True

type

boolean

description

Show or hide line numbers

Whether line numbers are shown by default.

autocomplete

flags

--autocomplete

environment variable

EUPORIE_AUTOCOMPLETE

default

False

type

boolean

description

Provide completions suggestions automatically

Whether to automatically suggestion completions while typing in code cells.

autosuggest

flags

--autosuggest

environment variable

EUPORIE_AUTOSUGGEST

default

True

type

boolean

description

Provide line completion suggestions

Whether to automatically suggestion line content while typing in code cells.

autoinspect

flags

--autoinspect

environment variable

EUPORIE_AUTOINSPECT

default

False

type

boolean

description

Display contextual help automatically

Whether to automatically display contextual help when navigating through code cells.

max_stored_outputs

flags

--max-stored-outputs

environment variable

EUPORIE_MAX_STORED_OUTPUTS

default

100

type

integer

description

The number of inputs / outputs to store in an in-memory notebook

Defines the maximum number of executed “cells” to store in case the console session is saved to a file or converted into a notebook.

connection_file

flags

--connection-file or --kernel-connection-file

environment variable

EUPORIE_CONNECTION_FILE

type

string

description

Attempt to connect to an existing kernel using a JSON connection info file

If the file does not exist, kernel connection information will be written to the file path provided.

If the file exists, kernel connection info will be read from the file, allowing euporie to connect to existing kernels.

show_file_icons

flags

--show-file-icons

environment variable

EUPORIE_SHOW_FILE_ICONS

default

False

type

boolean

description

Show file icons in the file manager

Whether file icons should be shown in the file manager.

These icons exist in the unicode private use area, and may require custom fonts such as awesome-terminal-fonts or nerdfonts to be installed.

show_status_bar

flags

--show-status-bar

environment variable

EUPORIE_SHOW_STATUS_BAR

default

True

type

boolean

description

Show the status bar

Whether the status bar should be shown at the bottom of the screen.

mouse_support

flags

--mouse-support

environment variable

EUPORIE_MOUSE_SUPPORT

type

boolean

description

Enable or disable mouse support

When set to True, mouse support is enabled. When set to False, mouse support is disabled.

app

environment variable

EUPORIE_APP

default

'notebook'

type

string

options

['console', 'edit', 'hub', 'notebook', 'preview']

description

The application to launch

The name of the application to launch.

host

flags

--host

environment variable

EUPORIE_HOST

default

''

type

string

description

The host address to bind to

This determines the host address the euporie hub SSH server will bind to.

port

flags

--port

environment variable

EUPORIE_PORT

default

8022

type

integer

description

The port for the ssh server to use

This determines which port euporie will listen on for connections to euporie hub.

host_keys

flags

--host-keys

environment variable

EUPORIE_HOST_KEYS

default

['/etc/ssh/ssh_host_ecdsa_key']

type

array

description

Host keys to use for the SSH server

One or more SSH host key files to use for the euporie hub SSH server.

client_keys

flags

--client-keys

environment variable

EUPORIE_CLIENT_KEYS

default

['~/.ssh/authorized_keys']

type

array

description

Client public keys authorized to connect

One or more OpenSSH-style authorized_keys files, containing public keys for authorized clients.

auth

flags

--auth

environment variable

EUPORIE_AUTH

default

True

type

boolean

description

Allow unauthenticated access to euporie hub

When set, users will be able to access euporie hub without authentication.

Warning

This option is dangerous, as arbitrary code can be executed through euporie apps.

show_cell_borders

flags

--show-cell-borders

environment variable

EUPORIE_SHOW_CELL_BORDERS

default

False

type

boolean

description

Show or hide cell borders.

Whether cell borders should be drawn for unselected cells.

external_editor

flags

--external-editor

environment variable

EUPORIE_EXTERNAL_EDITOR

type

string

description

Set the external editor to use.

A command to run when editing cells externally. The following strings in the command will be replaced with values which locate the cell being edited:

{top}
{left}
{bottom}
{right}
{width}
{height}

This is useful if you run euporie inside a tmux session, and wish to launch your editor in a pop-up pane. This can be achieved by setting this parameter to something like the following:

"tmux display-popup -x {left} -y {bottom} -w {width} -h {height} -B -E micro"

save_widget_state

flags

--save-widget-state

environment variable

EUPORIE_SAVE_WIDGET_STATE

default

True

type

boolean

description

Save a notebook’s widget state in the notebook metadata

When set to True, the state of any widgets in the current notebook will be saves in the notebook’s metadata. This enables widgets to be displayed when the notebook is re-opened without having to re-run the notebook.

max_notebook_width

flags

--max-notebook-width

environment variable

EUPORIE_MAX_NOTEBOOK_WIDTH

default

120

type

integer

description

Maximum width of notebooks

The maximum width at which to display a notebook.

expand

flags

--expand

environment variable

EUPORIE_EXPAND

default

False

type

boolean

description

Use the full width to display notebooks

Whether the notebook page should expand to fill the available width

show_scroll_bar

flags

--show-scroll-bar

environment variable

EUPORIE_SHOW_SCROLL_BAR

default

True

type

boolean

description

Show the scroll bar

Whether the scroll bar should be shown on the right of the screen.

show_side_bar

flags

--show-side-bar

environment variable

EUPORIE_SHOW_SIDE_BAR

default

False

type

boolean

description

Show the side-bar

Whether the side-bar should be shown at the side of the screen.

tab_mode

flags

--tab-mode

environment variable

EUPORIE_TAB_MODE

default

'stack'

type

string

options

['stack', 'tile_horizontally', 'tile_vertically']

description

The method used to display multiple tabs

Determines how multiple tabs are displayed when more than one tab is open. * stack displays one tab at a time with a tab-bar * tile_horizontally displays tabs side-by-side * tile_vertically displays tabs one-atop-the-next

always_show_tab_bar

flags

--always-show-tab-bar

environment variable

EUPORIE_ALWAYS_SHOW_TAB_BAR

default

False

type

boolean

description

Always show the tab bar

When set, the tab bar will always be shown - otherwise the tab bar is only shown when multiple tabs are open.

background_pattern

flags

--background-pattern or --bg-pattern

environment variable

EUPORIE_BACKGROUND_PATTERN

default

2

type

integer

options

[0, 1, 2, 3, 4, 5]

description

The background pattern to use

The background pattern to use when the notebook is narrower than the available width. Zero mean no pattern is used.

background_character

flags

--background-character or --bg-char

environment variable

EUPORIE_BACKGROUND_CHARACTER

default

'·'

type

string

description

Character for background pattern

The character to use when drawing the background pattern.

Recommended characters include: “·”, “⬤”, “╳”, “╱”, “╲”, “░”, “▒”, “▓”, “▞”, “╬”

run_after_external_edit

flags

--run-after-external-edit

environment variable

EUPORIE_RUN_AFTER_EXTERNAL_EDIT

default

False

type

boolean

description

Run cells after editing externally

Whether to execute a cell immediately after editing in $EDITOR.

run

flags

--run

environment variable

EUPORIE_RUN

default

False

type

boolean

description

Run the notebook files when loaded

If set, notebooks will be run automatically when opened, or if previewing a file, the notebooks will be run before being output.

show_top_bar

flags

--show-top-bar

environment variable

EUPORIE_SHOW_TOP_BAR

default

True

type

boolean

description

Show the top bar

Whether the top bar should be shown at the top of the screen.

save

flags

--save

environment variable

EUPORIE_SAVE

default

False

type

boolean

description

Save the notebook after running it

If set, notebooks will be saved after they have been run. This setting only has any affect if the run setting is active.

show_filenames

flags

--show-filenames

environment variable

EUPORIE_SHOW_FILENAMES

default

False

type

boolean

description

Show the notebook filenames when previewing multiple notebooks

If set, the notebook filenames will be printed above each notebook’s output when multiple notebooks are being previewed.

cell_start

flags

--cell-start

environment variable

EUPORIE_CELL_START

type

integer

description

The first cell to include in the preview

When set, only cells after the given cell index will be shown.

cell_stop

flags

--cell-stop

environment variable

EUPORIE_CELL_STOP

type

integer

description

The last cell to include in the preview

When set, only cells before the given cell index will be shown.

output_file

flags

--output-file

environment variable

EUPORIE_OUTPUT_FILE

default

'-'

type

string

description

Output path when previewing file

When set to a file path, the formatted output will be written to the given path. If no value is given (or the default “-” is passed) output will be printed to standard output.

page

flags

--page

environment variable

EUPORIE_PAGE

default

False

type

boolean

description

Pass output to pager

Whether to pipe output to the system pager when previewing a notebook.