Skip to main content

pytermwm

PyPI Downloads Python 3.9+ License: LGPL-2.1-or-later

1.0.8 is out (2026-11-06): programs inside windows (neovim, vim, tmux, a shell over SSH) can now copy to the clipboard with OSC 52, the command prompt gets Shift+arrow text selection, copying soft-wrapped lines no longer adds line breaks, and a bracketed paste whose end marker is split across reads no longer freezes input. 1.0.7 fixed clicking back into the terminal application to give it OS focus accidentally starting (and copying) a text selection, with terminals (seen with Windows Terminal over SSH) that send the focus-in escape only after that click. 1.0.6 covered the same bug for terminals that send focus-in before the click. 1.0.5 fixed a paste whose closing marker never arrives freezing keyboard/mouse input for that client. 1.0.4 fixed up to 100ms of extra input lag on Alt-key combos, arrow keys and other Escape-prefixed sequences. 1.0.3 added dialog poll <id> and pytermwm dialog-wait <id> for retrieving a dialog's result directly, and fixed several macOS-specific hangs and gaps. 1.0.2 added pytermwm version showing which version each running session runs and fixed long status line messages blanking the status line. 1.0.1 brought pip install pytermwm, the nes, matrix and dos themes, SVG screenshots and asciicast recordings of the whole screen, much cheaper background effects, and Windows fixes. See the changelog and the announcement.

A modern terminal window manager in pure Python ("tmux for 2026"): tiled, floating and docked windows, desktops, themes, a status line with a built-in prompt, and four ways to drive it: the keyboard, a CLI, an HTTP/web API with a browser UI, and an MCP server so AI agents can operate your terminal.

Runtime dependency: PyYAML only (everything else is the standard library). Python 3.9+ on Linux, macOS and Windows 10 1809+ (ConPTY; Windows Terminal recommended). See Platforms.

pipx install pytermwm              # recommended: its own environment, `pytermwm` and `ptw` on your PATH
pip install pytermwm               # or with pip; upgrade later with `pip install -U pytermwm` / `pipx upgrade pytermwm`
brew install pez2001/pytermwm/pytermwm   # or with Homebrew (macOS, Linux); upgrade with `brew upgrade pytermwm`
pytermwm                           # attach to (or create) the default session
pytermwm --standalone              # everything in one process, no daemon
pytermwm --web 8765                # ... and serve the web UI (prints the URL with its token)
pytermwm doctor                    # check that this machine can run everything

ptw is a shorter name for the same command, and python -m pytermwm works too. Or run straight from a checkout without installing anything: pip install -r requirements.txt, then the wrapper ./ptw ... on Linux/macOS, ptw.cmd ... or python ptw.py ... on Windows.

Try it in a minute

python -m pytermwm attach                      # M-Enter new window, M-h/j/k/l move, M-Space cycle layout, M-/ help
python -m pytermwm up                          # build the workspace from .pytermwm.yaml and attach
python -m pytermwm run -- htop                 # from another shell: open a window in the running session
python -m pytermwm send -t 1 -l -e "ls -la"    # type into window 1 (-l literal text, -e presses Enter)
python -m pytermwm capture -t 1                # read what window 1 shows
python -m pytermwm ctl "layout grid"           # any WM command
python -m pytermwm web                         # print the web UI URL
python -m pytermwm mcp                         # MCP server on stdio for an agent

Screenshots

pytermwm with the default theme: a shell, a chart and a notes window, tiled

modern modern nes nes dos dos
matrix matrix amiga amiga c64 c64
bbs bbs mc mc hacker hacker
light light command palette command palette (M-p) effect matrix effect matrix behind a floating window

A recorded tour (windows, layouts, the palette, themes, an effect): docs/media/demo.cast - play it with asciinema play docs/media/demo.cast or inside pytermwm with replay docs/media/demo.cast.

Making screenshots and recordings

Every picture and recording above is generated, not hand-made: python3 scripts/make_media.py drives a headless session through scripted scenes and writes docs/media/ again (--only themes|palette|effect|cast, --out DIR). The recording runs on a virtual clock, so it is the same on a slow or a fast machine.

From a running session (keys, prompt, pytermwm ctl, HTTP or MCP) the same is one command:

screenshot                       # the whole screen as an SVG in the state directory
screenshot ~/shot.svg            # .svg picture, .ans ANSI art (cat it) or .txt plain text; -f overwrites
record-screen ~/demo.cast        # asciicast v2 of the whole screen: every window, border and the status line
record-screen-stop
record -t 2 ~/win.cast           # just one window's output (record-stop to finish)

What is in the box

area what
windows terminal, piped process, file/FIFO tail, text, help, log, status, viewer, dirwatch, chart, debugger; history, virtual size, scrollbars, overflow modes, CP437 conversion
layouts recursive tile, master, spiral, columns, rows, grid, centered, monocle, table (spans), float, docking; multiple desktops
look themes default light modern hacker bbs mc c64 amiga nes matrix dos + your own YAML themes; borders, shadows, focus cues, effects (matrix, plasma, starfield, fire, rain, ANSI/ASCII art from a file or directory)
UI status line with pluggable segments, prompt in the status line, command palette, autocompletion, history, dialogs
sessions detachable server, multi-client attach, save/restore
control one command registry shared by hotkeys, prompt, CLI, HTTP, MCP, rules and scripts; scoped tokens (read, agent) for dashboards and AI agents
automation YAML rules (output/idle/exit/interval/event/status triggers, undo after N seconds) and Python scripts/plugins with hot reload
web live screen with keyboard/mouse/paste, window list, console, config editor, rule builder, script editor, plugin and log views
projects .pytermwm.yaml + pytermwm up builds a whole workspace (desktops, windows, env) and is safe to repeat
recording asciicast v2 recording of the whole screen (record-screen) or any window (record), a replay window (replay), screenshots as SVG / ANSI / text (screenshot)
selection PuTTY-style mouse selection with copy on release, word/line/rectangle modes, keyboard copy mode, paste buffer, OSC 52 and a copy view for terminals without it
plugins docker, btop-style monitor, MQTT (own client), SSH, background effects, OpenAI-compatible chat; write your own in one file
I/O stdio re-routing between windows, pytermwm pv progress reporting to the status line, cmd | pytermwm pipe viewers

Platforms

Linux / macOS Windows
terminals pty ConPTY (ctypes, no extra package)
session endpoint unix socket in $XDG_RUNTIME_DIR (0700) loopback TCP, random port + 128-bit key in %LOCALAPPDATA%\pytermwm\run\<name>.port
config / state ~/.config/pytermwm, ~/.local/state/pytermwm %APPDATA%\pytermwm, %LOCALAPPDATA%\pytermwm
default shell $SHELL or /bin/sh $PYTERMWM_SHELL, pwsh, powershell, then %COMSPEC%
system stats /proc Win32 API and tasklist (no load average / network counters)

!shell rule actions quote variables for the platform's shell; on Windows characters that cmd/PowerShell treat specially are replaced by _. PYTERMWM_THREADED_IO=1 and PYTERMWM_TCP=1 switch a Linux box to the Windows I/O model, which is how the Windows code paths are tested without Windows.

Documentation

Tests

./run_tests                  # or run_tests.cmd / python run_tests.py; no install needed (-k PATTERN, -v, -f, --list)
./run_tests --threaded-io --tcp   # the whole suite in the Windows I/O model
python scripts/smoke.py      # end-to-end check of the real CLI/daemon/HTTP/MCP (any OS)
./ptw doctor                 # environment check

On Windows run_tests runs the portable subset by default (--all for everything); a few tests need a POSIX shell. GitHub Actions (.github/workflows/ci.yml) runs Linux, macOS and Windows.

The browser test in tests/test_web_ui.py runs only when playwright and a Chromium are installed (set PTW_CHROMIUM to the binary); it is skipped otherwise.

Releasing

  1. Set __version__ in pytermwm/__init__.py, move the Unreleased entries in CHANGELOG.md under a ## [X.Y.Z] - date heading, and merge that to main.
  2. Push the tag: git tag -a vX.Y.Z -m "pytermwm X.Y.Z" && git push origin vX.Y.Z. .github/workflows/release.yml checks the tag against the code and the changelog, builds the sdist and wheel, uploads them to PyPI with Trusted Publishing, then creates the GitHub release (the changelog section as its notes, marked "Latest") and announces it in Discussions → Announcements. Publishing a release in the GitHub web UI creates the tag and does the same.

One-time setup on pypi.org: Account → Publishing → add a (pending) publisher for owner pez2001, repository pytermwm, workflow release.yml, environment pypi. To try a build locally: pip install build twine, python -m build, twine check dist/*.

Security notes

The web server binds to 127.0.0.1 and requires a random token (Bearer header, or ?token= once which becomes an HttpOnly SameSite=Strict cookie). Host and Origin are checked, so DNS-rebinding and cross-site requests are refused. eval and the python console are off unless allow_eval: true. Rule variables are shell-quoted. Read docs/api.md before binding to another interface.

Metadata

Release files for pytermwm 1.0.8

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

Source distribution (sdist)

Source distribution for pytermwm 1.0.8
File Size Uploaded Provenance Actions
pytermwm-1.0.8.tar.gz 342.2 kB With provenance Details for pytermwm-1.0.8.tar.gz

Built distribution (wheel)

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

Total release size: 619.2 kB

Release files / pytermwm-1.0.8.tar.gz

Download URL pytermwm-1.0.8.tar.gz
Size 342.2 kB
Tags Source
SHA-256 checksum
How to use checksums
7c1765357525d627c8a832504c962aa5856275de1e9a39b3f9d07a579201da1e
BLAKE2b-256 checksum
How to use checksums
08ddb7446d73a808466cae1b7f85260ae8ffa37b1d4caa355a8ae4bc58ed36aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 6, 2026.

Transparency log

Release files / pytermwm-1.0.8-py3-none-any.whl

Download URL pytermwm-1.0.8-py3-none-any.whl
Size 277.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
848ddcb45be507a253afb39388b984530bec769106d60c9af63f439e8f4a57f4
BLAKE2b-256 checksum
How to use checksums
b6bd56d02ae268f5e1a4613fc69c411f1f0ac3bab2df047456c0e3840864d8fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 6, 2026.

Transparency log

Security for pytermwm 1.0.8

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 pytermwm-1.0.8.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 Nov 6, 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.

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