A modern reimagining of the Python progresssss bar.
psnek not only supports the expected features of progress bars such as nesting and writing, but it also supports adding more metrics and logs to easily see how important data changes as the progress bar...progresses.
https://github.com/user-attachments/assets/17cd51ae-500d-49f1-9262-4344681ee415
Additionally, the bars are extremely customizable, from changing the gradient color, to changing whether text is printed above or below the progress bar, to changing the height of the progress bar to fit even more metrics!
https://github.com/user-attachments/assets/7a6f5fe0-6476-48a9-973b-915eb7791b30
More useful features of psnek:
- Semantic colorling of Bars that turn amber when a loop stalls and red when it's stuck, dynamically judged against the loop's own pace.
- A statistically significant completion ETA that is marked with a
~when it can't be trusted with confidence. - Support for printing pandas and polars DataFrames (or just a list of
dicts) directly into the panel with proper formatting. (fun tip: try sorting a DataFrame before writing to see the top results!) - System notification support (OSC 777) for terminal emulators that support it (e.g. Ghostty, kitty) to alert the user to completion and stalls. These will only fire for long-running tasks to prevent annoyances.
- Support for CI and AI coding agents by automatically disabling styles and avoiding carriage returns.
- Zero Python dependencies so importing is fast and
psnekis unlikely to break with future Python releases. - A dedicated Jupyter Notebook renderer which owns all text output during it, and avoids an issue present in
tqdm.notebookthat massively bloats the resulting notebook with dead widgets. - Async/Multithreading support for threads, processes, and asyncio, with support for free-threaded Python.
- Massive performance increases despite all the features added above:
psnekhas 1/10th the overhead oftqdmand has far fewer updates and consumes much lower bandwidth when used remotely.
Installation
psnek can be installed from PyPI (Python 3.11+):
pip3 install psnek
uv pip install psnek
Demo
Wrap any iterable with track() and optionally give it a description.
import psnek
for path in psnek.track(paths, "resize"):
resize(path)
For anything else, you can update a Bar manually, from any thread. Use with so the bar is always closed and so an Exception marks it as failed:
options = psnek.Options(unit="B", scale="iec")
with psnek.Bar(total=size, desc="upload", options=options) as bar:
for chunk in chunks:
send(chunk)
bar.update(len(chunk))
You can add status fields after the metrics with status(), either as keywords or as a dict whose keys don't need to be valid Python names. Setting a field to None removes it.
bar.status(loss=0.137, lr=3e-4)
bar.status({"val loss": 0.142, "lr": None})
Bars started inside another bar's loop are drawn as a tree below it. By default, only the top-level bar's final line is kept once it finishes.
for epoch in psnek.track(3, "epochs"):
for batch in psnek.track(batches, f"epoch {epoch + 1}"):
...
⣄ epochs ⣿⣿⣿⣿⣿⣿⣿⣿⡆⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 33.3% 1/3 0:21<0:22 11.1s/it
└─⠋ epoch 2 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 41.2% 412/1000 0:09<0:12 45.8it/s
└─⢰ eval ⣿⣿⣿⣿⣿⣿⡏⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 26.6% 17/64 0:00<0:01 41.0it/s
To print a line above whatever bars are live:
psnek.write("finished shard", 3)
Jupyter Notebook with a tour of everything above.
The Snek
Each cell of the bar is an 8-dot Braille character that fills in eight steps, so consecutive cells read as one winding coil: ⠀ ⡀ ⡄ ⡆ ⡇ ⡏ ⡟ ⡿ ⣿. When the total is unknown, the snake slithers back and forth, led by a face that reflects the run's mood. If progress stops for an unusually long time for that loop, the snake slows down and the bar turns amber (stalled 12s), then red (stuck 48s).
The Panel
While a bar is live in a terminal, anything you print() or log is routed into a panel drawn below the bars instead of breaking them. You can also write to the panel directly:
bar.log("processed", path) # append a message to the panel, like logging
bar.log("loss spiked", level=logging.WARNING) # with a logging level
bar.panel("worker 1: idle\nworker 2: busy") # replace the panel's content
bar.panel(None) # clear it
bar.write("saved model") # print permanently above the bars, like print()
log() is for messages about the run: each one starts with its level (debug, info, warn, error, or fatal), and rises in salience with it, from a faint debug line to bold warnings and errors in the bar's own colors. Options(log_time=True) starts each message with the system time. Logged messages stay indented under the bars once the panel pushes them above, while write() prints its text as-is, flush left:
16:30:33 info batch 10 ingested
checkpoint saved: ingest-015.parquet
⢰ ingest ⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⣀ 90.0% 27/30 0:00<0:00 38.5it/s rows=27000
⡇ 16:30:33 warn batch 18: 3 malformed rows skipped
⡇ 16:30:33 error upload of batch 24 failed
⡇ retrying in 1s
panel() also lays out structured data as a borderless table: a dict, dataclass, or named tuple becomes bold keys beside their values, while a list of them (or a polars or pandas DataFrame) becomes rows under a bold header. Only the rows that fit are formatted, so it's cheap to call every step.
bar.panel({"loss": 0.13761, "learning_rate": 3e-4, "epoch": 3})
bar.panel([{"model": "llama", "acc": 0.912}, {"model": "gpt2", "acc": 0.6, "note": "base"}])
⡇ loss 0.1376
⡇ learning_rate 0.0003000
⡇ epoch 3
⡇ model acc note
⡇ llama 0.9120
⡇ gpt2 0.6000 base
CI and AI Agents
Without a terminal (CI, pipes, and AI coding agents such as Claude Code or Codex), psnek prints plain, newline-terminated status lines with no escape codes: a start line, one every 10 seconds, one whenever a bar stalls, gets stuck, or recovers, and a final summary.
ingest: 0.0% 0/100 0:00<--:-- --it/s
ingest: 50.0% 50/100 0:06<~0:06 stalled 5s 40.6it/s
ingest: 53.0% 53/100 0:07<~0:06 7.3it/s (recovered)
ingest: 100.0% 100/100 0:08 done 13.9it/s
psnek detects common CI and agent environment variables automatically. (Jupyter Notebook)
Parallel and Async
pmap() maps a function over items with progress and returns the results in input order.
results = psnek.pmap(fetch, urls, "fetch", workers=16)
For asyncio, atrack() wraps an async iterable, gather() works like asyncio.gather(), and amap() works like pmap() with at most workers calls running at once. Both gather() and amap() count each call as it completes, and cancel the remaining calls if one fails.
async for message in psnek.atrack(stream, "messages"):
...
pages = await psnek.gather(*(fetch_page(url) for url in urls), desc="fetch")
pages = await psnek.amap(fetch_page, urls, "fetch", workers=16)
On a free-threaded build of Python such as python3.14t, CPU-bound pmap() on plain threads scales across cores and update() stays cheap even when many threads call it at once. (Jupyter Notebook)
Options
psnek.Options holds the presentation settings, and can be shared by any number of bars. (Jupyter Notebook)
Some useful options include:
unit: Label for counts and rates (default:"it")scale:"si"(1000) or"iec"(1024) number prefixes (default:"none")height: Rows the bar spans (default: 1)gradient: Color the bar with its gradient, with your own list or tuple of"#RRGGBB"colors, or (False) in the terminal's text color (default: True)stream: Where the bar is drawn (default:sys.stderr)notify: Allow desktop notifications about the bar (default: True)
AI Disclosure
psnek was mostly made using Claude Opus 5.5 with checks and balances, both a) as an experiment into seeing how well its design sense can translate into the terminal domain and b) the idea to use Braille subcharacters as a snake for a progress bar came to me after a glass of wine and I wanted to see how well Opus 5.5 could execute it. Opus 5.5 was successful, although it required significant back and forth on the design and a substantial amount of user testing (for example, to catch visual state/layout changes that happen too quickly for agents).
I have reviewed all the code and documentation copy manually in this repository and I stand by it professionally.
Miscellaneous Notes
- The terminal GIFs/videos were made using vhs, which apparently Opus 5.5 can use well. An additional postprocessing step was added to crop the resulting video to only salient dimensions in order to cut down on unnecessary space and reduce file size. The demo files and
vhstapes are available in the demo folder. - The default gradient colors were chosen to fit two specific criteria: a) sufficient color contrast for both dark and light terminal themes and b) colorblind friendliness against other semantic bar colors. The palette is similar to viridis sans the yellows which don't play well with light backgrounds.
- A bar is considered stalled once the wait since its last progress is past the smoothed mean of its gaps plus 3 standard deviations (and at least 5 seconds), and stuck past 9 standard deviations (and at least 30 seconds). The first 3 gaps are never flagged, so a slow first step such as loading a model is fine.
- The ETA drops its
~only when psnek is 99% confident it is within 10% (or a second). During warm-up, irregular loops, changes in pace, and stalls, it keeps the~. - In a terminal, psnek sends a desktop notification when a bar gets stuck, fails, or a long run finishes, on terminals that support it (Ghostty, WezTerm, foot, iTerm2, and kitty). Nothing is sent inside tmux or screen.
- All text psnek draws is sanitized, so captured output can't move the cursor or spoof the display.
To Be Added
- CLI support for non-Python pipes (implemented but not tested)
- Canonical
psnekcallbacks for all major Python machine learning frameworks (e.g. Hugging Face transformers, Keras)
Maintainer/Creator
Max Woolf (@minimaxir)
Max's open-source projects are supported by his Patreon and GitHub Sponsors. If you found this project helpful, any monetary contributions to the Patreon are appreciated and will be put to good creative use.
License
MIT
Metadata
Release files for psnek 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| psnek-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for psnek-0.1.0-py3-none-any.whl |
Release files / psnek-0.1.0-py3-none-any.whl
| Download URL | psnek-0.1.0-py3-none-any.whl |
|---|---|
| Size | 83.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a1672aaa62087bc6f50b57783c0d2a01c265b0d16739a0b02522f454b8b4d08
|
|
BLAKE2b-256 checksum How to use checksums |
03c10df82d91a1b96dc954ed6936bdf571671c5d524395c24a750fd9eb2a4ca5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for psnek 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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.