servery

A zero-dependency, pure-Python HTTP file server — a batteries-included python -m http.server.

Run it right now — no install:

# with uv — fetches a matching Python and runs servery, nothing to install:
uvx servery ./public --port 8000

# …or one self-contained file, straight from a pipe (latest release):
curl -fsSL https://github.com/mjbommar/servery/releases/latest/download/servery.py | python3 - ./public -p 8000

uvx (from uv) is the easiest path — it even fetches a matching Python for you. The piped servery.py is the released package amalgamated into one auditable file (pure stdlib). It runs code, so inspect it first if you like (curl -fsSL <url> | less), pin a version (…/releases/download/v1.6.0/servery.py), or grab the servery.pyz zipapp — both are attached to every release.

Serve or share a directory over HTTP with the niceties people expect from tools like miniserve or npx serve — rich sortable directory listings, file upload, HTTP Basic Auth, HTTPS, range/resumable downloads, on-the-fly archive download, even HTTP/2 and opt-in HTTP/3 — while the core depends on nothing but the Python standard library.

$ servery                                  # serve the current directory on http://127.0.0.1:8000
$ python -m servery ./public --port 9000
$ servery --upload --auth me:secret        # password-protected drop box
$ servery --tls-cert cert.pem --tls-key key.pem --http2   # HTTPS + HTTP/2
$ servery ./docs --preview --metadata       # render Markdown/code; index by title

Features

• Rich directory listings — sizes, modified times, directories first, fully escaped; sortable columns (?C=&O=, Apache convention), a ?q= name filter, a ?ext= file-type facet, a breadcrumb trail, per-type icons, relative timestamps, inline size bars, an aggregate metrics strip, a pure-SVG modification timeline, per-file download (?download=1), pagination, and a cookie-backed light/dark/auto theme — all server-side with no JavaScript.
• File preview, opt-in — --preview adds ?preview=1: Markdown rendered to HTML, source code syntax-highlighted (Python via the stdlib's own tokenize, plus ~35 more — C/Rust/Go/JS/TS, LaTeX, SQL, YAML, HTML…), notebooks, JSON re-indented, CSV as a table, and images/audio/video inline. ?preview=source reads any of them as highlighted source instead. Zero dependencies, no JavaScript, raw HTML always escaped.
• Document metadata, opt-in — --metadata reads inside files (bounded, nothing executed): front matter, Python docstrings + __version__, LaTeX \title{}, HTML <title>, PEP 621 fields, image dimensions, ID3, PDF Info. Adds a Title/Author column, ?meta=author:ada / ?meta=tag:draft filters, title/author sorting, and ?metadata=1 JSON for a file or a whole directory (curl … | jq).
• Correct downloads — RFC 9110 Range/206 (resumable), strong ETags, the full conditional-request ladder (If-None-Match/If-Modified-Since/If-Range → 304/412), and zero-copy sendfile. Opt-in RFC 9530 integrity digests — send Want-Repr-Digest and get a Repr-Digest: sha-256=:…: over the whole file (even for a ranged/parallel download), a standardized replacement for a .sha256 sidecar.
• HTTPS — bring your own cert (--tls-cert/--tls-key) or get an ad-hoc self-signed one with --tls-self-signed (zero-dependency, generated at startup — handy for a quick encrypted LAN share). ALPN + HSTS over TLS.
• Automatic HTTPS (Let's Encrypt), zero-dependency — --acme example.com obtains a browser-trusted certificate over ACME HTTP-01 (RFC 8555) and serves it. The JWS + CSR are built from servery's own RSA/DER primitives, so trusted auto-TLS needs no third-party crypto. Staging by default; --acme-production for real certs.
• HTTP Basic Auth — single credential or a pre-hashed user:sha256:…, constant-time compare.
• Upload — opt-in --upload, streaming multipart/form-data (no cgi), atomic writes, bounded size, overwrite off by default. Resumable uploads too: PUT with Content-Range appends a chunk and survives an interrupted transfer (the Google/S3 convention — works from bare curl, 308 + Range to resume). Same-target writes are serialized across upload, WebDAV, archive extraction, and TFTP.
• Archive download — stream any directory as tar.gz or zip (?archive=tar.gz), or tick the per-entry checkboxes and zip just the selected files/folders — all with no JavaScript. --max-archive-streams adds per-worker admission before headers.
• Access logging — --access-log PATH writes HTTP/1 file-serving responses in Common Log Format (clf/combined/json). Synchronous writes remain the measured default; setting --access-log-queue opts into a count- and byte-bounded batched writer. Backpressure versus drop, batching, and drain are configurable; the diagnostic stderr log remains separate.
• WebDAV — --dav lets macOS Finder / Windows Explorer / Linux mount the share as a network drive (read-only); --dav-write adds write (PUT/DELETE/MKCOL/MOVE/COPY). Pure stdlib, same path-safety as everything else; writes honor --auth. Writable DAV defaults to enforced exclusive locks, with explicit class1 and compatibility modes.
• CORS, SPA fallback, cache control, security headers — --cors, --spa, --cache, with nosniff everywhere and a scoped CSP on generated pages (off via --no-security-headers).
• On-the-fly compression — text-like responses (and the directory listing) are compressed when the client accepts it (RFC 9110: q-value negotiation, Vary, distinct ETag, ranges served identity). Prefers zstd when the interpreter has it (Python 3.14+, compression.zstd) and the client accepts it, else gzip. Already-compressed media is left alone (keeps sendfile). Off via --no-compress.
• Frictionless LAN sharing — --qr prints a scannable QR of the LAN URL (pure-stdlib QR encoder, with auto-detected LAN IP even on a 0.0.0.0 bind), and --discoverable advertises over mDNS/DNS-SD so the share shows up in Finder / file managers and at <host>.local.
• HTTP/2 — --http2 enables a pure-stdlib HTTP/2 server (ALPN h2 over TLS, or h2c prior-knowledge). The HPACK and frame codecs are implemented against the RFCs with no third-party package.
• HTTP/3 — optional, via pip install servery[http3] (the aioquic QUIC stack); the core stays zero-dependency. It runs beside the TCP fallback and advertises its live UDP port via Alt-Svc; large HTTP/2/3 files stream above a configurable buffering threshold.
• TFTP — opt-in --tftp also serves the directory over TFTP (UDP, RFC 1350) for PXE boot and network gear, with blksize/tsize/timeout options; read-only unless --tftp-write. Pure stdlib. No auth or encryption — trusted LAN / lab networks only (off by default).
• Safe by default — binds 127.0.0.1, path-traversal + symlink-escape protection, a default socket timeout, a 256-connection/session ceiling, distinct HTTP/2/TFTP budgets, optional HTTP/1 idle/request-count reuse limits, an opt-in cross-transport stalled-write deadline, and loud warnings when you expose it or run auth without TLS.
• Free-threading ready — runs under the no-GIL builds (3.13t/3.14t); immutable config, no module-level mutable state.

Install

With uv (recommended — manages Python for you):

uvx servery                    # run ad-hoc, nothing installed
uv tool install servery        # …or install the `servery` command

Or with pip:

pip install servery            # core: zero dependencies
pip install servery[http3]     # optional HTTP/3 (aioquic)

Python 3.13+ (free-threaded builds supported).

Library use

from servery import Config, serve

serve(Config.create("./public", host="127.0.0.1", port=8000))

A note on dependencies

The core has zero third-party runtime dependencies — enforced by a CI gate that fails the build if the wheel ever declares one. HTTP/3 is the single, opt-in exception: it requires a real QUIC + crypto stack the standard library does not provide, so it lives behind the servery[http3] extra and never burdens the core. (For the curious, servery._oscrypto proves the standard library can reach AEAD crypto with zero PyPI dependencies via ctypes → the OS OpenSSL — the foundation a future native HTTP/3 could build on.)

It lives in the file-server lane (share a folder), not the web-framework lane — there is no routing or app-building here. It is a dev / LAN / ad-hoc sharing tool, not a hardened public-internet server.

Documentation

📖 Full documentation site → mjbommar.github.io/servery — getting started, task-oriented guides with examples, recipes, how to extend it, and a full CLI reference.

The deep-dive design docs (also rendered on the site):

Development

Requires uv. All gates run locally exactly as in CI:

uv sync                      # dev tooling (never ships in the wheel)
uv run pre-commit install    # local commit gates
make check                   # lint (ruff) + type (ty) + security (bandit) + tests
make build                   # build + zero-dependency gate

CI runs the suite on Linux/macOS/Windows × CPython 3.13/3.14, the free-threaded 3.13t/3.14t builds, and 3.15. See CONTRIBUTING.md.

A reproducible per-transport benchmark suite (pytest-benchmark) lives in benchmarks/:

uv run --group bench pytest benchmarks/   # HTTP/1.1, TLS, HTTP/2, WSGI, CGI, ASGI, proxy, …

See BENCHMARKS.md for reference numbers, the HTTP/3 case, the regression workflow, and the controlled static/WSGI/ASGI comparisons against nginx, Caddy, Gunicorn, and Uvicorn.

License

MIT