Skip to main content

tinyterminal

A terminal emulator in a native window. xterm.js renders the screen inside a frameless WebKitGTK window (pywebview, through wesktop); behind it one PTY and one WebSocket per tab, with the PTY side written against the Python standard library only.

Install

uv tool install --python /usr/bin/python3 tinyterminal   # or: pipx install tinyterminal
tinyterminal

Linux with GTK 3 and WebKitGTK, and a Python that can import the distribution's PyGObject. That is the system interpreter, so install with it explicitly: uv prefers its own downloaded interpreters, which cannot import the distribution's GTK bindings, while pipx uses the system one by default. On Fedora the two packages are python3-gobject and webkit2gtk4.1; other distributions name them differently.

Keys

Key Action
Ctrl+Shift+T new tab
Ctrl+Shift+W close tab
Ctrl+PageUp / Ctrl+PageDown previous / next tab
Ctrl+Shift+C / Ctrl+Shift+V copy selection / paste

What it does

  • Tabs, each its own login shell on its own PTY, titled from the OSC 0/2 title the shell sets and falling back to the shell's name. Closing the last tab closes the window.
  • Light and dark, both faces of the GNOME palette. The theme button cycles system, light and dark; on system the window follows the desktop's setting live.
  • The fastest renderer that works. The page probes for a webgl2 context and loads xterm's WebGL addon, falls back to the canvas addon, and shows which one is live at the right of the tab bar. A WebGL context loss switches to canvas and relabels.
  • Flow control that reaches the shell. The server counts every byte sent as unacknowledged until xterm's parser has consumed it, and above 1 MiB it stops reading the PTY, so the kernel's PTY buffer applies back-pressure to the program producing the flood. Nothing is ever buffered unboundedly in the server.
  • Its own window chrome. The window is frameless and transparent: the rounded card the page draws is the window silhouette, dragging goes to the compositor, and eight handles around the frame hand an interactive resize to it.
  • Clipboard through navigator.clipboard, falling back to the desktop's own clipboard through GDK when the web view refuses.

Known gaps

  • Linux and GTK 3 only in practice. The resize handles, the clipboard fallback and unmaximizing all call the GTK toplevel directly. On another pywebview backend those do nothing; nothing else has been tried.
  • No search, no per-tab titles you can edit, and no scrollbar styling beyond a thin native one.
  • allowProposedApi: true is on, which xterm 6 requires for Terminal.unicode -- the Unicode 11 addon registers into it. No other proposed API is used.
  • Opened in a plain browser rather than its own window, the page cannot close anything when the last tab exits, and the clipboard has only its web API path.
  • A face switch can lag in a screenshot. Late in a long scripted session a capture can show the previous face's top bar over an already-switched terminal. The page's computed style is correct, and no repaint the page can force changes it: WebKitGTK is holding that region's rasterisation.

Development

uv run python -m tinyterminal            # run it from the checkout
uv run pytest                            # the headless PTY + WebSocket suite
./scripts/fetch-assets.sh                # re-vendor the pinned xterm.js build
timeout 120 uv run python scripts/screenshot-test.py   # drives the real window

The vendored xterm.js build is not committed. scripts/xterm-versions.txt pins the versions, scripts/fetch-assets.sh downloads exactly those from the npm registry into src/tinyterminal/static/vendor/ (curl and tar, no node), and hatch_build.py runs that script during a build so the wheel carries the engine.

Layout

src/tinyterminal/server.py     PTY (openpty/fork/execvpe) + WebSocket bridge + flow control
src/tinyterminal/app.py        routes, window chrome, the js_api the page drives the window with
src/tinyterminal/static/       the frame, tab bar, themes, renderer choice, keys, clipboard
scripts/fetch-assets.sh        re-vendors the pinned engine
scripts/screenshot-test.py     windowed scene runner, writes screenshots/
tests/                         headless backend suite
bin/cli.js                     the npm shim, which runs the installed Python app

License

MIT

Metadata

Release files for tinyterminal 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tinyterminal 0.1.0
File Size Uploaded Provenance Actions
tinyterminal-0.1.0.tar.gz 28.2 kB With provenance Details for tinyterminal-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tinyterminal 0.1.0
File Interpreter ABI Platform Actions
tinyterminal-0.1.0-py3-none-any.whl Python 3 none any Details for tinyterminal-0.1.0-py3-none-any.whl

Total release size: 283.3 kB

Release files / tinyterminal-0.1.0.tar.gz

Download URL tinyterminal-0.1.0.tar.gz
Size 28.2 kB
Tags Source
SHA-256 checksum
How to use checksums
dc9e495abc0af8e3de68d27e0c80a0f8265edecc7527919b269cdbcf64964b7f
BLAKE2b-256 checksum
How to use checksums
6959cf5e0874b4585802287d6e6429519a4cee49ba38d9c1d0aec55fa4e42c43
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.

Transparency log

Release files / tinyterminal-0.1.0-py3-none-any.whl

Download URL tinyterminal-0.1.0-py3-none-any.whl
Size 255.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ac2eae5a7f727fa222599b3ef1da97d0419df1ab32763ad6dbcdb7744b18e54
BLAKE2b-256 checksum
How to use checksums
a3b205536a5413d5bbaaa51facdada6abd9111ad2b1b54f04a45d0d474a2938f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.

Transparency log

Security for tinyterminal 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tinyterminal-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page