static-http

static-http is a tiny dependency-free Python utility that starts a temporary static HTTP server in the current directory with byte-range support for quick local workflows.

It is intentionally focused on temporary file serving for local development, manual testing, media playback, and archive inspection.

Why this exists

python -m http.server is excellent for quick sharing but does not implement byte-range request handling. static-http fills that gap with a small CLI that keeps the behavior predictable and easy to reason about.

Install

uvx static-http
pipx run static-http
python -m pip install static-http

Quick start

static-http

uvx static-http

By default:

• Serves the current working directory.
• Binds to 0.0.0.0.
• Listens on port 8080.
• Uses a threaded HTTP server.
• Handles GET, HEAD, and single-range requests.
• Sends Cache-Control: no-cache, max-age=0, must-revalidate so browsers revalidate reused local URLs.
• Sends Last-Modified and ETag validators for file responses.
• Hides dot-prefixed and platform-hidden files/directories unless --include-hidden is used.

CLI

static-http supports these options:

• -p, --port PORT — listening port. 0 requests an OS-assigned port.
• -d, --directory PATH — root directory to serve. Default is the current directory.
• -b, --bind ADDRESS — bind address. Default is 0.0.0.0.
• --localhost-only — equivalent to --bind 127.0.0.1.
• --cors — adds Access-Control-Allow-Origin: *.
• --header "Name: Value" — repeatable custom headers.
• --no-dir-list — disable directory listing responses when no index file exists.
• --open — open the server URL in the default browser after startup.
• --qr — render a terminal QR code for the server URL.
• --no-cache — send Cache-Control: no-store instead of the default revalidation policy.
• --quiet — explicitly keep per-request logs suppressed. This is the default.
• --verbose — print detailed startup/binding information.
• --include-hidden — include dot-prefixed and platform-hidden files/directories in normal serving and directory listings.
• --version — print package version and exit.
• --about — print project and license information and exit.

Examples

static-http --open
static-http --qr
static-http --no-cache
static-http --quiet
static-http --verbose
static-http --include-hidden
static-http --port 9000 --cors
static-http --no-dir-list

QR codes

--qr prints a terminal QR code for the selected server URL. For the default all-interface bind, it prefers a discovered LAN URL when one is available; otherwise it falls back to localhost.

The built-in QR renderer is intentionally dependency-free and sized for normal localhost/LAN URLs. If the URL is too long or the terminal is too narrow, static-http prints a warning and keeps serving.

Shutdown

Press Q or q in the focused terminal to stop the server. Ctrl+C also triggers a graceful shutdown.

Range support

GET requests support single byte ranges with examples:

curl -H "Range: bytes=0-99" http://localhost:8080/video.mp4 -o part.bin
curl -H "Range: bytes=100-" http://localhost:8080/video.mp4 -o tail.bin
curl -H "Range: bytes=-500" http://localhost:8080/video.mp4 -o suffix.bin

The server returns 206 Partial Content for satisfiable ranges, 416 Range Not Satisfiable when the range is outside the file, and 400 Bad Request for invalid range syntax.

Security note

static-http is intentionally a temporary local development/file-serving tool, not a production web server.

By default it binds to 0.0.0.0, which can expose the selected directory to other clients that can reach your machine. It has no authentication, authorization, TLS, upload handling, or production hardening. Use --localhost-only when you only need access from the same machine, and use trusted networks for LAN sharing.

License

MIT