Need help with miniserve?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

svenstaro
2.4K Stars 111 Forks MIT License 1.1K Commits 45 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

# 8,210
Rust
Arch Li...
Flask
webasse...
286 commits
# 44,378
Rust
D
chalk
vscode
53 commits
# 46,490
Objecti...
sentry
watchos
trackpa...
24 commits
# 276,063
Rust
retroga...
HTML
Shell
21 commits
# 382,825
Shell
C
osc
Rust
10 commits
# 76,484
Ember
webasse...
curl
d3-modu...
10 commits
# 2,957
query-l...
python-...
mvvm-fr...
wechat-...
7 commits
# 169,896
Haskell
Google
google-...
Rust
6 commits
# 257,354
Rust
Shell
HTML
static-...
6 commits
# 487,023
TypeScr...
Rust
5 commits
# 61,841
Ruby
Homebre...
TeX
ruby-on...
5 commits
# 43,054
Rust
Shell
C
ncurses
4 commits
# 330,399
desktop...
Shell
C++
ss13
4 commits
# 115,427
Rust
Homebre...
typeset...
opam
4 commits
# 250,802
Rust
Android
React N...
ios-lib
3 commits
# 72,954
Rust
Common ...
rabbit
distrib...
3 commits
# 367,853
Shell
ami
nix
PureScr...
2 commits
# 527,914
Shell
C#
C++
file-fo...
2 commits
# 28,277
C
ffmpeg
libav
sdl2
1 commit
# 151,028
Go
Rust
gRPC
nextjs
1 commit

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.

Screenshot

Screenshot

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 192.168.0.1 --random-route /tmp
# Serving path /private/tmp at http://192.168.0.1/c789b6

Bind to multiple interfaces:

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

Upload a file using
curl
:

# in one terminal
miniserve -u .
# in another terminal
curl -F "[email protected]$FILE" http://localhost:8080/upload\?path\=/

(where

$FILE
is the path to the file. This uses miniserve's default port of 8080)

Features

  • 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 (with light and dark theme support)
  • Scan QR code for quick access
  • Shell completions
  • Sane and secure defaults

Usage

miniserve 0.13.0
Sven-Hendrik Haase , Boastful Squirrel 
For when you really just want to serve some files over HTTP right now!

USAGE: miniserve [FLAGS] [OPTIONS] [--] [PATH]

FLAGS: -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

    --random-route
        Generate a random 6-hexdigit route

-V, --version
        Prints version information

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

OPTIONS: -a, --auth ... Set authentication. Currently supported formats: username:password, username:sha256:hash, username:sha512:hash (e.g. joe:123, joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3) -c, --color-scheme Default color scheme [default: squirrel] [possible values: squirrel, archlinux, zenburn, monokai] -d, --color-scheme-dark Default color scheme [default: archlinux] [possible values: squirrel, archlinux, zenburn, monokai] --header

... Set custom header for responses --index 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]

    --print-completions <shell>
        Generate completion file for a shell [possible values: zsh, bash, fish,
        powershell, elvish]
-t, --title <title>
        Shown instead of host in page title and heading

ARGS: Which path to serve

How to install

Packaging status

On Linux: Download

miniserve-linux
from the releases page and run
chmod +x miniserve-linux
./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
./miniserve-osx

Alternatively install with Homebrew.

brew install miniserve
miniserve

On Windows: Download

miniserve-win.exe
from the releases page and run
miniserve-win.exe

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

cargo install miniserve
miniserve

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

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

Shell completions

If you'd like to make use of the built-in shell completion support, you need to run

miniserve
--print-completions 
and put the completions in the correct place for your shell. A few examples with common paths are provided below:
# For bash
miniserve --print-completions bash > ~/.local/share/bash-completion/miniserve
# For zsh
miniserve --print-completions zsh > /usr/local/share/zsh/site-functions/_miniserve
# For fish
miniserve --print-completions fish > ~/.config/fish/completions/miniserve.fish

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 0.0.0.0
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.

Releasing

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 
  • cargo release 
  • Releases will automatically be deployed by Github Actions.
  • Docker images will automatically be built by Docker Hub.
  • Update Arch package.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.