---

Cheap observability for Python processes, with a browser UI and almost no setup.

Live demo: https://demo.plotsrv.com
See a live instance of plotsrv rendering plots, tables, JSON, and HTML from a daily process visualising home sensor/meteorological data.

plotsrv is a lightweight Python server for exposing live Python objects and on-disk files in a single browser UI. It gives you quick visibility into pipelines, experiments, batch jobs, and long-running processes without needing a full observability stack.

Add a decorator to functions you want to expose, or publish artifacts directly from your code. Fire up the server with a single command, and plotsrv takes care of discovery, view registration, and object-specific rendering automatically.

Key features:

• Browser UI built on FastAPI for viewing live outputs in one place
• Automatic rendering for common Python outputs: plots, tables, JSON, text, HTML, images, code, and tracebacks
• Minimal setup: decorate functions and launch the server
• AST-based discovery of decorated views, so the UI can pre-populate navigation on startup
• Optional on-disk snapshots, with historical browsing and configurable retention
• Freshness tracking, so you can quickly see when a process is delayed or stale
• Configuration via plotsrv.yaml, including UI settings
• CLI-first workflow, with Python entry points available where needed

It can also watch files on disk and expose them in the same UI.

Get going

1. Install plotsrv

pip install plotsrv

Or

uv add plotsrv

2. Start the server

Provide a script, module or entire package.

plotsrv run your_module.py --host 127.0.0.1 --port 8000

You can also start the server from Python if needed.

3. Expose views from your code

The main pattern is to decorate functions whose output you want to expose:

from plotsrv import plotsrv

@plotsrv(label="sales", section="insights")
def sales_plot():
    return fig

@plotsrv(label="latest", section="insights")
def latest_results():
    return df

plotsrv inspects the returned object and chooses an appropriate renderer automatically.

You can also publish artifacts directly instead of using decorators:

from plotsrv import publish_artifact

publish_artifact({"status": "ok", "rows": 123}, label="summary")

Watching files on disk

plotsrv can also expose files directly from disk, which is useful for logs, reports, HTML files, JSON outputs, CSVs, and generated artifacts.

plotsrv run src.etl --host 127.0.0.1 --port 8000 \
  --watch /var/log/etl_log.txt --watch-label etl-log --watch-section log-files --watch-tail --no-truncate

Status

plotsrv is currently pre-0.1.0 and still evolving, but is already usable for real workflows.

License

plotsrv is licensed under the Apache License 2.0.

See the LICENSE file for full details.