Quick start

# Install (see more options below)
uv tool install webdev

# Serve the current directory on http://localhost:8080
webdev

# Serve a specific folder
webdev ./public

# See every option
webdev --help

Installation

With uv (recommended):

uv tool install webdev

With pipx:

pipx install webdev

Or with plain pip into an environment of your choice:

pip install webdev

Features

• 🗂️ Serve any directory — passed as the first positional argument; defaults to the current directory.

• 🩹 Graceful when the folder disappears — responds with 404 instead of crashing if the served directory is removed, and recovers automatically the moment it is recreated. Paths are resolved against the live filesystem on every request — ideal for build systems that clean and rebuild output.

• 🔀 Automatic port selection — if the base port is busy, the next free port in a range is used. Can be forced to a single exact port.

• 🔮 Serve a not-yet-existing folder — --future assumes the folder will be created later.

• 🎨 Modern dark directory index — breadcrumbs, file-type icons, human-readable sizes, modified dates and client-side sortable columns. Themable: drop a new directory under webdev/templates/<theme>/.

• 🔁 Live reload — connected browsers refresh automatically on file changes (via a WebSocket; a tiny auto-reconnecting snippet is injected into HTML).

• 📱 Instant mobile testing — a QR code and LAN URL are printed at startup so you can open the site on your phone.

• 🌈 Colorized, level-aware logs for readable output.

• ⚡ No-cache headers for always-fresh development content.

• 🧭 SPA fallback — optionally serve index.html for unknown routes.

• 📦 Gzip, CORS and optional HTTPS (self-signed if no cert/key is given).

• ⚙️ Config file — every option can be set via webdev.toml (or a [tool.webdev] table). Precedence: CLI flag > config file > default.

Usage

$ webdev --help
usage: webdev [-h] [-v] [--version] [-i IP] [-p PORT] [-f] [-r RANGE] [-u]
              [--reload | --no-reload] [--cache] [--no-cache]
              [--spa | --no-spa] [--gzip | --no-gzip] [--cors | --no-cors]
              [--qr | --no-qr] [--color | --no-color]
              [--https | --no-https] [--cert CERT]
              [--key KEY] [--theme THEME] [--config CONFIG]
              [path]

Examples:

# Serve the current directory on http://localhost:8080
webdev

# Serve ./public on a forced port, over HTTPS, without live reload
webdev -p 3000 -f --https --no-reload ./public

# Single-page app: fall back to index.html for client-side routes
webdev --spa ./dist

# Serve a build output folder that does not exist yet
webdev --future ./dist

# webdev.toml
port = 3000
force_port = true
spa = true
cors = true

Development

The development workflow is driven by tox using uv as the backend (via tox-uv). uv is the only tool you need preinstalled:

# Lint, format-check and type-check
tox -e style

# Run the test suite
tox -e test

# Build and verify the distribution
tox -e build

# Build, install in a throwaway venv and run (pass args after --)
tox -e run -- -p 3000 ./public

Each environment declares its own tooling dependencies in tox.ini so it installs only what it needs.

Changelog

License

Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.