Installation

Wijjit targets Python 3.11+ and modern terminals (Windows Terminal, iTerm2, Kitty, Alacritty, GNOME Terminal, etc.) with UTF-8 fonts that include box-drawing characters.

Requirements

  • Python >= 3.11 (matching pyproject.toml)

  • A virtual environment manager (uv is recommended for reproducible, cached installs)

  • No compiler needed — every runtime dependency ships pure-Python wheels

Install Wijjit

From source (development)

Clone the repository and install in editable mode with the dev extra (tests, linting, types, and docs):

git clone https://github.com/thomas-villani/wijjit.git
cd wijjit
uv sync --all-extras          # runtime + dev + images + xlsx into .venv

The equivalent with pip:

python -m venv .venv
source .venv/bin/activate      # or .venv\Scripts\activate on Windows
pip install -U pip setuptools wheel
pip install -e ".[dev]"

This pulls in pytest, pytest-cov, ruff, mypy, sphinx, myst-parser, sphinx-copybutton, and the other tools listed in pyproject.toml.

Verify your environment

Run a smoke test and docs build:

uv run pytest -m "not slow"
uv run python -c "import wijjit; print(wijjit.__version__)"  # confirm import + version
uv run make -C docs html           # ensure Sphinx extensions import correctly

You can also launch a demo:

uv run python examples/basic/hello_world.py

Dependencies

Core libraries installed automatically:

  • jinja2 – template engine for layouts.

  • prompt-toolkit – keyboard/mouse input, screen buffering.

  • rich – ANSI rendering utilities and colors.

  • pyperclip – clipboard integration for text inputs.

  • tinycss2 – CSS parsing for themes/styles.

  • wcwidth – correct display widths for wide/combining characters.

Optional images extra:

uv add "wijjit[images]"
# or
pip install "wijjit[images]"

This installs Pillow to enable the ImageView element (ASCII/ANSI image rendering). From a source checkout, use uv sync --extra images or pip install -e ".[images]" instead.

Optional additions in .[dev]:

  • myst-parser – Markdown support in docs.

  • sphinx-copybutton – quality-of-life improvements for code samples.

  • Testing/tooling stack (pytest, ruff, mypy, syrupy snapshots, etc.).

Platform notes

Windows

Use Windows Terminal or another modern emulator that supports UTF-8 and mouse reporting. Older cmd.exe shells will not render rounded borders correctly.

Linux

Ensure locale variables are set:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Clipboard copy/paste uses the system clipboard via pyperclip, which needs xclip or xsel installed (e.g. sudo apt install xclip). Without them, Wijjit falls back to an internal in-process clipboard — copy/paste still works inside the app, just not across other programs.

macOS

iTerm2 offers the best experience (truecolor + inline images). Apple’s default Terminal.app is also fully supported.

Troubleshooting

ImportError: No module named 'wijjit'

Confirm the package is installed (uv add wijjit / pip install wijjit, or pip install -e . for a source checkout) and that the correct virtual environment is active.

Broken borders or glyphs

Switch to a font with box-drawing characters (e.g., Fira Code, JetBrains Mono). On Windows, prefer Windows Terminal over cmd.exe.

Slow rendering / lag

Disable high-frequency animations, trim overly large tables, or run inside a truecolor terminal rather than nested multiplexers.

Next steps