🌟 For when you really just want to serve some files over HTTP right now!


miniserve - a CLI tool to serve files and dirs over HTTP

miniserve - a CLI tool to serve files and dirs over HTTP

CI Docker Cloud Build Status Crates.io license Stars Downloads Lines of Code

For when you really just want to serve some files over HTTP right now!

miniserve is a small, self-contained cross-platform CLI tool that allows you to just grab the binary and serve some file(s) via HTTP. Sometimes this is just a more practical and quick way than doing things properly.



How to use

Serve a directory:

miniserve linux-distro-collection/

Serve a single file:

miniserve linux-distro.iso

Require username/password:

miniserve --auth joe:123 unreleased-linux-distros/

Require username/password as hash:

pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve --auth joe:sha256:$pw unreleased-linux-distros/

Generate random 6-hexdigit URL:

miniserve -i --random-route /tmp
# Serving path /private/tmp at

Bind to multiple interfaces:

miniserve -i -i -i ::1 /tmp/myshare


  • Easy to use
  • Just works: Correct MIME types handling out of the box
  • Single binary drop-in with no extra dependencies required
  • Authentication support with username and password (and hashed password)
  • Mega fast and highly parallel (thanks to Rust and Actix)
  • Folder download (compressed on the fly as .tar.gz or .zip)
  • File uploading
  • Pretty themes
  • Scan QR code for quick access


miniserve 0.11.0
Sven-Hendrik Haase <[email protected]>, Boastful Squirrel <[email protected]>
For when you really just want to serve some files over HTTP right now!

    miniserve [FLAGS] [OPTIONS] [--] [PATH]

    -D, --dirs-first
            List directories first

    -r, --enable-tar
            Enable tar archive generation

    -z, --enable-zip
            Enable zip archive generation

            WARNING: Zipping large directories can result in out-of-memory exception because zip generation is done in
            memory and cannot be sent on the fly
    -u, --upload-files
            Enable file uploading

    -h, --help
            Prints help information

    -P, --no-symlinks
            Do not follow symbolic links

    -o, --overwrite-files
            Enable overriding existing files during file upload

    -q, --qrcode
            Enable QR code display

            Generate a random 6-hexdigit route

    -V, --version
            Prints version information

    -v, --verbose
            Be verbose, includes emitting access logs

    -a, --auth <auth>...
            Set authentication. Currently supported formats: username:password, username:sha256:hash,
            username:sha512:hash (e.g. joe:123,
    -c, --color-scheme <color-scheme>
            Default color scheme [default: squirrel]  [possible values: squirrel, archlinux,
            zenburn, monokai]
    -d, --color-scheme-dark <color-scheme-dark>
            Default color scheme [default: archlinux]  [possible values: squirrel, archlinux,
            zenburn, monokai]
        --header <header>...
            Set custom header for responses
        --index <index_file>
            The name of a directory index file to serve, like "index.html"

            Normally, when miniserve serves a directory, it creates a listing for that directory. However, if a
            directory contains this file, miniserve will serve that file instead.
    -i, --interfaces <interfaces>...
            Interface to listen on

    -p, --port <port>
            Port to use [default: 8080]

    -t, --title <title>
            Shown instead of host in page title and heading

            Which path to serve

How to install

Packaging status

On Linux: Download miniserve-linux from the releases page and run

chmod +x miniserve-linux

Alternatively, if you are on Arch Linux, you can do

pacman -S miniserve

On OSX: Download miniserve-osx from the releases page and run

chmod +x miniserve-osx

Alternatively install with Homebrew.

brew install miniserve

On Windows: Download miniserve-win.exe from the releases page and run


With Cargo: Make sure you have a recent version of Rust. Then you can run

cargo install miniserve

With Docker: If you prefer using Docker for this, run

docker run -v /tmp:/tmp -p 8080:8080 --rm -it svenstaro/miniserve /tmp

Binding behavior

For convenience reasons, miniserve will try to bind on all interfaces by default (if no -i is provided). It will also do that if explicitly provided with -i or -i ::. In all of the aforementioned cases, it will bind on both IPv4 and IPv6. If provided with an explicit non-default interface, it will ONLY bind to that interface. You can provide -i multiple times to bind to multiple interfaces at the same time.

Why use this over alternatives?

  • darkhttpd: Not easily available on Windows and it's not as easy as download and go.
  • Python built-in webserver: Need to have Python installed, it's low performance, and also doesn't do correct MIME type handling in some cases.
  • netcat: Not as convenient to use and sending directories is somewhat involved.


This is mostly a note for me on how to release this thing:

  • Make sure CHANGELOG.md is up to date.
  • cargo release --dry-run <version>
  • cargo release <version>
  • Releases will automatically be deployed by Github Actions.
  • Docker images will automatically be built by Docker Hub.
  • Update Arch package.
  • Interfaces


    1. Report if any address fails to bind

    ::actix_web::HttpServer::bind() fails if and only if ALL the requested addresses fail to bind! an the docs require multiple calls for multiple addresses.

    2. Fix: faulty bahvior when setting -i

    Currrently, address is converted into!

    Closes #470

    3. Fix: On Windows, miniserve binds only to localhost( by default

    This is in part because of the issue mentioned above, and also because binding to :: binds only to IPv6 by default on Windows!

    Closes #405 Also reported by @KaneGreen in #470.

    4. cross-platform default binding addresses

    Currently, miniserve by default binds to both and :: ant the same time. This behaviour has a problem:

    On some platforms (e.g. majority of linux distros and OSX?) , the :: address also accepts ipv4 connections. This makes these two addresses incompatible! See https://stackoverflow.com/questions/1618240/how-to-support-both-ipv4-and-ipv6-connections

    ~I currently have no idea how this should be fixed!~

    5. implement #422

    Closes #422

    opened by aliemjay 24
  • Themed errors

    Themed errors

    Error pages should now follow the query parameters the user had before. So, this respects the theme, but also the potential sorting parameters the user had (this is useful when using the go back to file listing link). Also, I implemented Copy for some of our enums, as it greatly reduce the boilerplate and makes the code more readable, I think.

    opened by ghost 22
  • File upload

    File upload

    This is my WIP for file uploading #6

    I would like to clean up my error handling and discus some ideas.

    • if we can upload files, maybe I should add option to delete files too
    • Is it ok to override existing files?
    • I think the ability to upload file should be behind CLI flag and not by default

    I've tested my code only under linux, but it seems ok.

    opened by vojta7 22
  • Add support for readme rendering

    Add support for readme rendering

    Fixes https://github.com/svenstaro/miniserve/issues/859

    Suggestions are welcome, I'm only implemented the basic render for now.

    Other things that might be needed:

    • user flag to turn on/off readme rendering
    • render html bits inside markdown (might to be fixed from markdown crate)
    • other formats besides .md (.txt and , maybe .org)
    opened by Atreyagaurav 20
  • Add support for media streaming (video files)

    Add support for media streaming (video files)

    Hi there!

    I've been using Miniserve for a quite a bit now, and I'm really enjoying this tool. But I find it misses a feature I'd personally would love to see: video streaming.

    If I go the URI of a picture for instance it will be displayed by the browser correctly. But if it's an ~~video~~ audio file (e.g. MP~~4~~3) it will be downloaded instead of being played.

    Would it be possible to implement support for these formats? I have no idea if it would be complicated, just thought I'd throw the idea here :)

    good first issue 
    opened by ClementNerma 17
  • Implement raw view to allow recursive downloading via wget

    Implement raw view to allow recursive downloading via wget

    Currently it's not easily possible to use wget to download a folder served with miniserve because the rendered directory listing contains links for the different .tar options, themes and whatnot.

    • This implements a raw view which can get accessed via http://.../somedir/foo/?raw and is a stripped down html version
    • Besides this it also implements a new ui element which contains a generated wget command to download this folder via wget

    This is probably a hackish attempt, but works quite well. If there's a chance of this feature getting merged, i would overhaul it, add integration tests and whatnot.

    opened by Jikstra 17
  • Split integration test into multiple files

    Split integration test into multiple files

    Fix https://github.com/svenstaro/miniserve/issues/85

    An additional issue arises: cargo test warns me of unused items in helper module. This happens because the items are only used by test functions in test-only context. I don't know how to fix this other than #[allow(dead_code)].

    opened by KSXGitHub 17
  • Resolve symlinks on directory listing

    Resolve symlinks on directory listing

    This has the benefit of showing the size and modification date of the pointed-to file. Symlink to directories now respects '--dirs-first' option and broken symlinks don't show up in directory listing.

    The only downside AFAIK is more syscalls when listing directories.

    @svenstaro Any input on this? should it be configurable? can we abandon the symlink symbol?

    opened by aliemjay 16
  • Download folders in .tar.gz format

    Download folders in .tar.gz format

    This is my WIP for solving #2 (only .tar.gz at the moment).

    The code isn't quite clean, the error handling needs some more work, and I have a bug on Mac OS X because user folders are wierd symlinks, and it causes the current code to fail. I'm investigating this issue.

    Otherwise, it works pretty well :)

    opened by ghost 16
  • add a default index serving option (#156)

    add a default index serving option (#156)

    Start addressing #156

    ~~Do you know where I should consume this option and how to configure active-web to serve the file? I started modifying fn configure_app( but couldn't figure out how to make it serve an index.html from within a configured directory root.~~

    opened by efx 15
  • Color schemes

    Color schemes

    So, here is my WIP to solve #51, and in a more general way, have different colour schemes. At the moment, I implemented 3 dark themes since I'm more comfortable designing them, but I'll eventually come up with a light theme (or multiple ones, if needed), I just have to find a nice way to make the colours fit together...

    I also did several improvements to the CSS in general (padding, back to top button bigger, and only visible on small screen (I can set it back if needed), etc). Also, I prepared the moment when we'll have several compression methods available. Download buttons should fit nicely next to each-other.

    I am open to any changes when it comes to the colours, or the design in general. Let's use this PR to fix everything that you don't like design-wise :)

    opened by ghost 15
  • uploading area didn't show with mixed arguments '-vDFgHqruzWo'

    uploading area didn't show with mixed arguments '-vDFgHqruzWo'

    After updating Docker Image from 0.19.2 to 0.22.0, uploading area and "Download .zip", which worked fine on 0.19.2, disappeared.


    Here is my configuration in docker-compose.yml:

        image: svenstaro/miniserve:0.22.0
        restart: always
        command: ' -p 8080 -vDFgHqruzWo  -t":)" /data'
          - /xxx:/data
          - /etc/localtime:/etc/localtime:ro

    Then I tried using a single -u (the command line became command: ' -p 8080 -u -vDFgHqrzWo -t":)" /data') and the uploading and "Download .zip" worked again. image

    opened by Karmenzind 0
  • [Question] Authenticated upload, anonymous download

    [Question] Authenticated upload, anonymous download


    I've been using miniserve for some time but have left uploads disabled as I don't want anyone to whom I send files being able to also upload files.

    Is there a way to achieve authenticated uploads with anonymous downloads allowed? My thought currently would be running two miniserve instances - one authenticated with uploads enabled (u.file.host) and one anonymous without uploads enabled (d.file.host) with both serving from the same path.

    Any suggestions on how to handle this?


    opened by oorzkws 1
  • The `wget` command from `--show-wget-footer` with `--random-route` doesn't include the random route.

    The `wget` command from `--show-wget-footer` with `--random-route` doesn't include the random route.

    Version: 0.20.0

    As an example, when I browse the wget footer says

    Download folder: wget -r -c -nH -np --cut-dirs=0 -R "index.html*" ""

    which, naturally, produces leads to a 404 error if you try to use it.

    opened by alexschrod 0
  • Will it support SMB server with auth?

    Will it support SMB server with auth?

    Thanks for implement this prefect tools. It helped a lot , we can use this tool and intergate into our system easily. Currently we faced an problems is we need to use SMB server to store our logs and traces and videos. So is it possible to add this feature?

    opened by chaooe 2
  • "Change theme" does not work properly

    "Change theme" absolutely does not work on iOS. I tried in Safari and Brave, no reaction at all.

    It does not work properly even on my computer in Brave in mobile view. When i click on the button, theme immediately changes: ChangeTheme

    On Android it works well.

    • miniserve: 0.20.0 in docker
    • MacOS 11.6.8:
      • Brave: Version 1.42.88 Chromium: 104.0.5112.81 (Official Build) (x86_64)]
    • iOS 15.6:
      • Brave: 1.41.1
      • Safari: 15.6
    • Android:
      • Brave: 1.41.100
    opened by EvgeniyDoctor 0
Sven-Hendrik Haase
Freelance consultant, DevOps and automation connoisseur, Arch Linux developer, hobbyist game and graphics programmer. Available for remote contracting.
Sven-Hendrik Haase
Static Web Server - a very small and fast production-ready web server suitable to serve static web files or assets

Static Web Server (or SWS abbreviated) is a very small and fast production-ready web server suitable to serve static web files or assets.

Jose Quintana 396 Sep 23, 2022
handle some lichess.org/tournament load with rust, while learning rust

lila-http Take some of the HTTP load away from lila. WIP! Arena tournaments Clients connected to a tournament page request new data about the tourname

Thibault Duplessis 19 Jul 5, 2022
Host These Things Please - a basic http server for hosting a folder fast and simply

http Host These Things Please - a basic HTTP server for hosting a folder fast and simply Selected features See the manpage for full list. Symlinks fol

thecoshman 354 Aug 30, 2022
Simple http server in Rust (Windows/Mac/Linux)

How it looks like? Screenshot Command Line Arguments Simple HTTP(s) Server 0.6.1 USAGE: simple-http-server [FLAGS] [OPTIONS] [--] [root] FLAGS:

LinFeng Qian 730 Sep 24, 2022
An HTTP library for Rust

hyper A fast and correct HTTP implementation for Rust. HTTP/1 and HTTP/2 Asynchronous design Leading in performance Tested and correct Extensive produ

null 10.3k Sep 19, 2022
[OUTDATED] A light HTTP framework for Rust

Rustful A light HTTP framework for Rust, with REST-like features. The main purpose of Rustful is to create a simple, modular and non-intrusive foundat

Erik Hedvall 872 Sep 2, 2022
Fully async-await http server framework

Saphir is a fully async-await http server framework for rust The goal is to give low-level control to your web stack (as hyper does) without the time

Richer Archambault 80 Jun 8, 2022
Low level HTTP server library in Rust

tiny-http Documentation Tiny but strong HTTP server in Rust. Its main objectives are to be 100% compliant with the HTTP standard and to provide an eas

null 755 Sep 21, 2022
:zap: fast http framework for rust

zap ⚡ The mission of zap is, to deliver a basic, but fast rust web server library. Documentation About This code is based on tokio's minihttp project,

Daniel Oltmanns 51 Jun 7, 2022
Add Facebook and Google authentication to your HTTP REST API in Actix-web

I created this project while learning Rust. Project shows how to handle Facebook and Google token verification in Rust using Actix-Web. Hope this help

null 36 Jun 30, 2022
Node.js http server framework powered by Hyper native binding.

hnsjs POC project. Install this test package yarn add @hnsjs/core Support matrix node10 node12 node14 node15 Windows x64 ✓ ✓ ✓ ✓ Windows x32 ✓ ✓ ✓ ✓

LongYinan 18 Aug 17, 2022
Akasio is a simple HTTP server that redirects traffic based on a JSON redirect table. This is its Rust implementation.

This page is inaccurate and is pending updates. Akasio (Rust) Description Akasio is a simple HTTP server that redirects traffic based on a JSON redire

K4YT3X 5 May 2, 2022
RUSTENGINE is the high-assurance HTTP server.

RUSTENGINE Table of Contents RUSTENGINE Table of Contents About RUSTENGINE Inspiration with Rust Features Compares with Nginx Build & Run About this R

FUNNY SYSTEMS 10 Aug 27, 2021
OxHTTP is a very simple synchronous HTTP client and server

OxHTTP is a very simple synchronous implementation of HTTP 1.1 in Rust. It provides both a client and a server.

Oxigraph 12 Sep 22, 2022
service_policy_kit is a Rust based toolkit for verifying HTTP services against policies.

Service Policy Kit service_policy_kit is a Rust based toolkit for verifying HTTP services against policies. You can: Build a complete testing framewor

null 20 Apr 17, 2022
A synchronous HTTP server built on hyper.

Astra Astra is a synchronous HTTP server built on top of hyper. use astra::{Body, Response, Server}; fn main() { Server::bind("localhost:3000")

Ibraheem Ahmed 20 Sep 19, 2022
Completely OBSOLETE Rust HTTP library (server and client)

OBSOLETION NOTICE This library is DEAD. It was a useful experiment and is now being replaced under the scope of the Teepee (experimentation grounds at

Chris Morgan 390 Aug 6, 2022
Archibald is my attempt at learning Rust and writing a HTTP 1.1 web server.

Archibald To be a butler, is to be able to maintain an even-temper, at all times. One must have exceptional personal hygiene and look sharp and profes

Daniel Cuthbert 4 Jun 20, 2022
A blazingly fast static web server with routing, templating, and security in a single binary you can set up with zero code. :zap::crab:

binserve ⚡ ?? A blazingly fast static web server with routing, templating, and security in a single binary you can set up with zero code. ?? UPDATE: N

Mufeed VH 672 Sep 18, 2022