simple-http-server: a Rust static file server with upload, SPA fallback and PKCS#12 TLS

What simple-http-server solves, and who reaches for it

Python's http.server is one command and no options. That is fine until you need the directory listing to be sorted, an index.html rendered automatically, a file uploaded from a browser form, or a single-page app to fall back to index.html for unknown paths. simple-http-server exists to cover that middle ground: more than a bare file server, far less than nginx. The README describes it as a "Simple static file server with directory listing, upload, basic auth, range requests, compression, CORS, SPA fallback, and optional PKCS#12 HTTPS support." It is aimed at developers serving build output, sharing a folder on a LAN, testing a front-end bundle, or standing up a small internal file drop. The Windows, Mac and Linux support in the repository description matters here, because the tool ships as a Rust binary rather than depending on a language runtime that may not be present on the target machine.

Inside the axum and tokio rewrite

Version 0.8.0 is labelled "Axum Rewrite" in the release notes, and Cargo.toml confirms the shape of that change: the crate depends on axum 0.8.8 with default features off and only http1, tokio, multipart and query enabled, plus tokio 1.50.0 with the rt-multi-thread, net, fs, io-util, time and sync features. So the server is a tokio multi-threaded runtime hosting an axum router over HTTP/1, with multipart parsing present specifically because uploads need it. The dependency list also tells you what the project deliberately does not carry: no templating engine, no database driver, no session store. Directory listing is rendered by the binary itself, and mime_guess maps file extensions to content types. Compression comes from flate2, and httpdate supplies the date formatting used for cache headers. The tls feature is an opt-in that pulls in openssl and tokio-openssl, and on Windows the openssl dependency is declared with the vendored feature, which means a Windows TLS build compiles OpenSSL from source instead of expecting a system library. That is a real build-time cost, and it is the price of keeping the default binary free of TLS.

Installing simple-http-server and serving a first folder

The README gives two install paths. The default build has no TLS and produces a smaller binary. The tls feature adds PKCS#12 HTTPS support and is disabled by default.

cargo install simple-http-server

For HTTPS support, install with the feature flag instead. Expect the build to take longer, particularly on Windows where OpenSSL is vendored and compiled.

cargo install simple-http-server --features tls

Once installed, the README's first example serves a folder with automatic index rendering. The -i flag enables rendering of index.html or index.htm when a directory is requested.

simple-http-server -i public

With no other flags the server binds 0.0.0.0 on port 8000, so the page is reachable at http://localhost:8000/ from the same machine. If you want a different port, -p takes one. If you want the browser opened for you, -o does that. Uploads are separate: the README's example for that is the following, where -u enables upload and -l 50M raises the size limit above the 8M default.

simple-http-server -u -l 50M .

The upload flag is documented as requiring a CSRF token, so a browser form that posts files needs the token handled by the page the server serves. The README warns that --csrf passes the token on the command line and that this is dangerous because the token may be visible in process listings.

Serving an SPA and running behind a path prefix

Two flags in the option list are easy to miss and change how the server behaves for real deployments. The first is --try-file, which the help text describes as serving a file in place of missing paths, with relative paths resolved against the server root and absolute paths used as-is. The README's SPA example uses it as a fallback so client-side routes do not 404.

simple-http-server --try-file dist/index.html dist

The alias --try-file-404 is also listed, which is the more descriptive name for what is happening. The second flag is --base-url, for when the server sits behind a reverse proxy that strips a prefix before forwarding. The help text says the value is normalized to start with a slash and to end with a slash when it is not root, and that it affects directory indexes and upload redirects.

simple-http-server --base-url /static/ .

Note the boundary of that feature. It changes the links the server generates and where uploads redirect; it does not make the server itself rewrite incoming paths. If your proxy forwards /static/foo to the server unchanged, the base URL is not going to fix the mismatch. The README's wording is specific about indexes and upload redirects, and that is the extent of the claim.

Where simple-http-server is the wrong tool

The upload path is the sharpest limitation. Upload is enabled by a flag, protected by a CSRF token, and gated by a size limit that defaults to 8M, but the option list shows no per-user accounts, no write-only drop mode, and no way to restrict uploads to a subdirectory. Anyone who can reach the server and obtain the token can write files into the served tree. The README's own warning about --csrf being dangerous because the token is visible in process listings should be read literally: passing a fixed token on the command line trades convenience for exposure. Basic auth, meanwhile, is a single -a user:pass pair, so there is no way to give different people different credentials or to revoke one without changing the password for everyone.

TLS has a similar edge. --cert expects a PKCS#12 file such as .p12 or .pfx, and the README states that PEM files are not accepted directly. If your certificate authority hands you PEM files, you need an openssl pkcs12 conversion step before the server will start, and the conversion is on you. The tls feature is also off in the default build, so a binary installed with plain cargo install simple-http-server simply will not have the --cert and --certpass options available. Compression is disabled on partial requests, per the help text, so range requests and gzip do not combine. And with a default of 3 worker threads, this is not a server you point at a high-traffic public endpoint; it is a server you point at a folder.

How it compares to the alternatives people actually use

The most common alternative is Python's http.server, which is what the related searches keep bringing up. The difference is scope rather than speed. Python's module serves a directory with a listing and nothing else: no upload, no basic auth, no compression, no CORS headers, no SPA fallback. It also requires a Python interpreter on the machine. simple-http-server compiles to a single binary, which is why the Windows and Linux searches exist, and it ships the extra features as flags rather than as code you write. The trade is that you need a Rust toolchain to install it via cargo, or a prebuilt binary from wherever you trust.

Against a general web server such as nginx, the difference runs the other way. nginx gives you a configuration language, virtual hosts, upstreams, rate limiting and a mature TLS story with PEM files. simple-http-server gives you none of that, and in exchange you get a command you can type from memory. If your requirement is already written down as an nginx config, this project will not replace it. If your requirement is "serve this folder to the people on my network, and let them drop files in it," the comparison is not close.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-27, which is recent enough that the project is being touched. The release history shows a major architectural change: v0.6.13 in 2025-06-30, then v0.6.14 on 2026-03-05, then v0.8.0 labelled "Axum Rewrite" on 2026-03-17, with Cargo.toml at version 0.8.1 and edition 2024. The jump from 0.6.x to 0.8.0 in twelve days is the upgrade risk to plan for. Anything you built against the older server implementation should be re-checked against the axum version, and the edition bump to 2024 means the crate now requires a recent Rust toolchain to build from source. The Makefile defines the project's own checks as cargo fmt, cargo clippy with all features and warnings denied, and cargo test with all features, followed by a Cargo.lock diff check. Running those locally is the fastest way to find out whether your toolchain matches.

The licence is MIT, stated in both the README's repository metadata and the Cargo.toml license field. That is permissive and short, but note that the optional tls feature links OpenSSL, which carries its own licence terms that are separate from the MIT licence of this crate. If you build with --features tls, the resulting binary includes OpenSSL, and the obligations attached to that dependency are yours to review. Nothing here is legal advice; read the licences yourself if redistribution matters.

Editorial conclusion

Adopt simple-http-server if you need a single binary that serves a directory with upload, SPA fallback or basic auth, and you are willing to build it with cargo. Do not adopt it if you need a hardened public-facing web server, an access-control model beyond a single username and password, or TLS from PEM files, because --cert only accepts PKCS#12 and the tls feature is off by default. Before you commit, verify on your own machine that the default 3 worker threads keep up with your request volume, that the 8M upload limit is what you want, and that your certificate converts cleanly to .p12.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. TheWaWaR/simple-http-server on GitHub