itsloopyo/qrdrop
Simple LAN file sharing over HTTP. Contribute to itsloopyo/qrdrop development by creating an account on GitHub.
0 stars · 0 forks · 0 watchers · Python
README
QRDrop 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. uvx qrdrop 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 cd ~/photos uvx qrdrop ╭──────────────────────────────────────────────────╮ │ 📂 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 --readonly The 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