Instant file sharing from your terminal. Serve the current directory over your local network with one command: get a URL, a memorable password, and a QR code your phone can scan in moments.
No setup, no fuss, ctrl+c and it's gone.
Getting Started
Run it without installing anything:
uvx qrdrop # Python 3.11+ via uv docker run --rm -p 8000:8000 -v "$PWD:/data" \ itsloopyo/qrdrop --public-host <your-LAN-IP> # no Python at all
Or install it (Python 3.11+):
pip install qrdrop pipx install qrdrop
See Docker below for port mapping, flags, and image details.
1. Share a directory
╭──────────────────────────────────────────────────╮
│ 📂 QRDrop v0.0.0 │
╰──────────────────────────────────────────────────╯
Serving: /home/you/photos
Local: http://localhost:8000
Network: http://192.168.1.42:8000
Password: ember-velvet-canyon
┌─ Scan for instant access ─┐
▄▄▄▄▄▄▄ ▄▄▄▄ ▄ ▄▄▄▄▄▄▄
█ ▄▄▄ █ ▄ █▀█▄ ▀ █ ▄▄▄ █
█ ███ █ █████▀█ █ ███ █
█▄▄▄▄▄█ ▄▀▄▀▄▀█ ▄ █▄▄▄▄▄█
▄▄ ▄▄ ▄ ▀█ █▄▀▄█▄ ▄ ▄
██▀▄▄█▄▀█▄▀█ ▀██ ▄ █▀█▀▀▄
█▄▀ ▀█▄▀▀▄▄▀▀ ▀▀▄ ██ ▀▀▀█
█▄█ ▀█▄▄▄▄█▀▄█▄█▄█▄ █▄▄█▄
█ █▀█▀▄ ▀█▀▄▀▄▀██▄██▄▀█▄▀
▄▄▄▄▄▄▄ ▀▀ ▄ █ █ ▄ █ ▀▀▄
█ ▄▄▄ █ ▄█▀█▄▀▄██▄▄▄█ ▄▀
█ ███ █ ▀ ▄█ ▀▀▀▀█▀ ▄▄▄██
█▄▄▄▄▄█ █▄█ ▄ ▀▄█▄▀▀▄▀▀█
└───────────────────────────┘
Press Ctrl+C to stop the server
If port 8000 is busy, QRDrop automatically picks the next free one.
2. Connect from another device
- Phone: scan the QR code. It encodes a pre-authenticated link, so you land in the file browser with no typing.
- Anything else: open the network URL and enter the three-word password.
3. Browse, view, download
The web UI lets you:
- Browse directories with breadcrumb navigation
- View files inline: syntax-highlighted code (Python, Rust, Go, TypeScript, shell, and dozens more), images, and PDFs
- Download any single file, or select several and grab them as one ZIP, TAR.GZ, or TAR.BZ2 archive
4. Restrict changes (optional)
QRDrop allows full access by default (downloads, uploads, delete, new folders + rename). Restrict it:
uvx qrdrop --upload # downloads and uploads only (no delete/rename) uvx qrdrop --readonly # downloads only (no writes at all)
Usage Examples
uvx qrdrop --port 9000 # custom port uvx qrdrop --password correct-horse # bring your own password uvx qrdrop --hide-dotfiles # exclude dotfiles from listings uvx qrdrop --bind 192.168.1.42 # bind one interface (default: 0.0.0.0) uvx qrdrop --timeout 7200 # expire sessions after 2 hours (default: never) uvx qrdrop --quiet # no banner, warnings-only logs
Note that QRDrop lists everything by default, including dotfiles. --hide-dotfiles is the opt-out.
CLI Reference
qrdrop [OPTIONS]
Options:
-p, --port PORT Port to serve on (default: 8000)
-b, --bind ADDRESS Address to bind to (default: 0.0.0.0)
--public-host HOST[:PORT]
Address to advertise in the Network URL and QR code.
Required for the QR code to work in Docker, where the
auto-detected IP is the container's (env: QRDROP_PUBLIC_HOST)
--password TEXT Use specific password instead of generating one
--hide-dotfiles Exclude files starting with '.' from listings
--upload Restrict writes to uploads only (no deletions or directory create/rename)
--readonly Disable all writes; browse and download only
--timeout SECONDS Expire sessions after this many seconds (default: sessions
last until the server stops)
-q, --quiet Suppress startup banner
--version Show version and exit
--help Show help and exit
Docker
Images are published to Docker Hub as itsloopyo/qrdrop on every release. Mount the directory you want to share at /data, forward a port to 8000, and pass your machine's LAN IP to --public-host, like this:
docker run --rm -p 8000:8000 -v /path/to/share:/data itsloopyo/qrdrop --public-host 192.168.1.50
--public-host matters: a container can only see its own internal IP (something like 172.17.0.2), so without it the Network URL and QR code point at an address no phone can reach. Find your LAN IP with ipconfig (Windows), ipconfig getifaddr en0 (macOS), or ip addr (Linux). -e QRDROP_PUBLIC_HOST=192.168.1.50 works too.
The startup banner, including the generated password and QR code, goes to the container logs, so run in the foreground or check docker logs. Any qrdrop flags can be appended:
docker run --rm -p 9000:8000 -v "$PWD:/data" itsloopyo/qrdrop --public-host 192.168.1.50:9000 --password correct-horse --readonlyThe container always listens on port 8000 internally; pick your external port with -p <port>:8000 rather than --port, and if it differs from 8000, include it in --public-host (as in the example above) so the advertised URLs use the published port.
The image is multi-stage (uv on Alpine), runs as a non-root user, and has a built-in healthcheck against /health. Writes are enabled by default, so the mounted directory must be writable by uid 1000 (or pass --readonly to serve without writes).
Development
The dev loop is pixi:
pixi run build # editable install with dev extras pixi run test # pytest with coverage pixi run test-e2e # Playwright end-to-end tests pixi run lint # ruff check pixi run format # ruff format pixi run dev # run qrdrop from source
QRDrop is built on Starlette, Uvicorn, Jinja2, and aiofiles.
License
MIT