miniserve

Serve a directory

$ miniserve [path/to/directory]

$ miniserve [path/to/file]

$ miniserve --auth [username]:[password] [path/to/directory]

miniserve [OPTIONS] [PATH]

PATH defaults to the current working directory if not specified.

--auth <USER:PASS>
    Enables HTTP Basic Authentication. Can be specified multiple times for different user credentials.

--dav
    Enables Web Distributed Authoring and Versioning (WebDAV), allowing clients to create, modify, and delete files on the server.

--fallback <FILE>
    Serves a specified file (e.g., index.html) when a requested path is not found. Useful for Single Page Applications (SPAs).

--header <NAME:VALUE>
    Adds a custom HTTP header to all responses. Can be used multiple times.

--interface <ADDR>
    Specifies the network interface or IP address to bind to. Default: 0.0.0.0 (all interfaces).

--index <FILE>
    Specifies the default file to serve when a directory is requested (e.g., index.html). Default: index.html.

--live-reload
    Enables live reloading for HTML files. When source files change, connected browsers automatically refresh. Ideal for web development.

--port <PORT>
    Specifies the port number to listen on. Default: 8080.

--qrcode
    Displays a QR code in the terminal for the server's address, making it easy to access from mobile devices.

--no-symlinks
    Disables following symbolic links that point outside the served directory for security reasons.

--spa
    Enables Single Page Application (SPA) mode. Any path not found will serve the index.html file, similar to --fallback index.html.

--tls-cert <FILE>, --tls-key <FILE>
    Enables HTTPS/TLS encryption by providing paths to a certificate file and its corresponding private key file.

--upload-files
    Allows clients to upload files to the served directory via a web interface.

--raw-ip
    Shows raw IP addresses in log output instead of attempting to resolve hostnames.

--verbose
    Enables verbose logging output, providing more detailed information about server activity.

-v, --version
    Prints the installed miniserve version information and exits.

-h, --help
    Prints a detailed help message about miniserve usage and available options, then exits.

miniserve is a versatile, cross-platform command-line utility designed for quickly serving files and directories over HTTP. Written in Rust, it provides a lightweight and self-contained web server ideal for development, local file sharing, or hosting static websites. Its primary goal is to offer a simple, "just-works" solution for common file serving needs without the overhead of traditional web servers. It boasts a variety of features including optional basic HTTP authentication, file upload capabilities, WebDAV support for remote file management, QR code display for easy mobile access, and live reloading for web development workflows. Its minimal configuration and single-binary distribution make it an excellent choice for rapid prototyping or ad-hoc sharing scenarios where a full-fledged web server might be overkill.

Security: While useful for local development and trusted networks, exposing miniserve directly to the public internet without proper authentication and TLS/HTTPS can pose significant security risks, especially when features like file upload or WebDAV are enabled.

Resource Usage: Designed for simplicity and quick deployment, miniserve might not scale as efficiently as full-fledged web servers (like Nginx or Apache) for very high traffic, complex routing, or advanced server-side processing needs.

Authentication Limitations: HTTP Basic Authentication, when used without TLS/HTTPS encryption, transmits credentials in plain text and is therefore not secure over untrusted networks. Always use --tls-cert and --tls-key when authentication is required over a network.

miniserve can typically be installed via common package managers (e.g., apt install miniserve on Debian/Ubuntu, brew install miniserve on macOS) or directly through Rust's package manager, cargo (cargo install miniserve). Being compiled into a single static binary, it's also very easy to download a pre-built executable and run it directly.

Quick File Sharing: Easily share files or entire directories between devices on a local network or with colleagues.

Web Development Server: Rapidly serve static HTML/CSS/JS applications during development, often combined with --live-reload for an improved workflow.

Temporary Download/Upload Point: Create an ad-hoc server to facilitate quick transfers, especially useful with --upload-files.

Single Page Application Hosting: Serve front-end JavaScript applications using --spa or --fallback to handle client-side routing.

miniserve is a modern utility, developed in Rust, which emphasizes performance, memory safety, and cross-platform compatibility. It emerged as a simpler, more robust alternative to older scripting-based one-liner servers (like Python's http.server) for quickly serving files. Its design philosophy prioritizes ease of use and minimal configuration, aiming to provide essential file serving capabilities in a single, portable executable without the overhead and complexity of traditional web servers.

python -m http.server(1), nginx(8), apache2(8), lighttpd(8), serve(1)