✦ ember

A modern, beautiful interactive Python shell. IPython's power — magics, history, debugging, extensions — rebuilt around a calm terminal UI.

See it in action

Why ember

• Readable sessions. Every cell is a block: your code, its output on a rail, and a footer with status, time, result type and Out[N].
• Help while you type. Completions with type icons, and live signatures with declared and inferred types — greet(name: str, times: int = 1) -> str — even for functions without annotations.
• Everything you use IPython for. 85 magics, obj?, !shell, session history in SQLite, %autoreload, %debug, %timeit, %prun, top-level await, GUI event loops…
• Runs IPython code. get_ipython(), IPython.display, custom magics and IPython extensions like line_profiler work unchanged.
• Feels good. Paste code straight from docs (>>> prompts are stripped), Shift+Enter for new lines, vi or emacs keys, three themes, two layouts.

Install

curl -fsSL https://raw.githubusercontent.com/arthurdaquinosilva/ember/main/install.sh | sh

The installer picks a suitable Python, puts ember in its own virtual environment (using pipx if you have it) and links the ember command into ~/.local/bin. Nothing is added to your projects' environments. Remove it any time with … | sh -s -- --uninstall.

Already a Python user? Install it yourself instead:

pipx install ember-shell     # the `ember` command everywhere, isolated from your projects
pip install ember-shell      # or into the current environment

The package is ember-shell on PyPI; the command is ember. To try the latest unreleased code: pip install git+https://github.com/arthurdaquinosilva/ember.git.

Then run ember. Requires Python 3.10+ on macOS or Linux.

Tip: ember runs code with the Python it's installed into. To work with a project's packages, install ember inside that project's virtual environment.

Quick tour

> import json
> data = {"name": "ember", "tags": ["repl", "python"]}
> data?                     # inspect any object (?? shows the source)
> json.*load*?              # wildcard name search
> files = !ls               # shell output as a list with .grep() / .fields()
> %timeit sorted(range(1000))
> %history -g json          # search history across sessions
> %xmode verbose            # tracebacks with local variables
> %debug                    # debugger on the last error (or breakpoint() in your code)
> %help                     # every key, syntax and magic

Shift+Enter needs a terminal that reports modified keys (iTerm2, WezTerm, Ghostty, kitty, xterm; inside tmux set extended-keys on). Alt+Enter and Ctrl+J work everywhere.

Documentation

Command line

ember                        # interactive
ember script.py args…        # run a file (-i to stay interactive afterwards)
ember -m package.module      # run a module
ember -c "print('hi')"       # run a command
ember --profile work --vi --theme nebula --no-startup

Development

git clone https://github.com/arthurdaquinosilva/ember.git && cd ember
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest              # unit tests
.venv/bin/python scripts/gen_magic_docs.py   # regenerate docs/magics.md
.venv/bin/python scripts/screenshot.py       # re-record docs/assets/demo.svg

ember is built on prompt_toolkit (input and layout), Rich (output), Jedi (completion and signatures) and Pygments (highlighting).

Known limits

• Terminal only — no Jupyter kernel; images (Image, SVG, %matplotlib inline) show a placeholder.
• !cmd streams through a pipe, so fully interactive programs (vim, less) should run outside ember.
• With the real IPython installed, ember leaves it untouched, so libraries calling IPython's own get_ipython() see no shell.

License

MIT © Arthur D'Aquino