Documentation

qrcp starts a small web server on your computer and prints a QR code with its address. Scan the code with your phone and the transfer happens in the phone’s browser: no app, no cloud, no account. When the transfer is done, qrcp exits.

Install qrcp from the packages page, then read on.

Contents: Quick start · Send files · Receive files · Network · HTTPS · Troubleshooting · Configuration · Command reference · Shell completion


Quick start

qrcp MyDocument.pdf   # send a file to your phone
qrcp receive          # receive files from your phone
  1. Run one of the commands above. qrcp prints a URL and a QR code.
  2. Scan the QR code with your phone’s camera (or any QR reader) and open the link.
  3. The file downloads on the phone, or an upload page opens. When the transfer is complete, qrcp exits.

The phone and the computer must be on the same network. The first time, qrcp may ask which network interface to use: pick the one connected to your Wi-Fi (see Choose the network).

Press q or Ctrl+C at any time to stop qrcp.


Send files to your phone

Sending is the default action, so these are equivalent:

qrcp MyDocument.pdf
qrcp send MyDocument.pdf
qrcp s MyDocument.pdf

What gets sent

You pass Example The phone receives
One file qrcp MyDocument.pdf The file itself
Several files qrcp MyDocument.pdf IMG0001.jpg A .zip archive with all of them
A folder qrcp Documents/ A .zip archive of the folder
One file, zipped qrcp --zip LongVideo.avi A .zip archive with the file

The archive is created in a temporary directory and deleted after the transfer.

When does qrcp exit?

By default qrcp stops as soon as the first browser has finished downloading, so the link works only once. To send the same file to several devices, or to download it more than once, keep the server running:

qrcp --keep-alive MyDocument.pdf    # or -k; stop it with q or Ctrl+C

Show the QR code differently

Situation Command
The QR code doesn’t scan well in your terminal’s colors qrcp --reversed MyDocument.pdf
You’d rather scan it from a browser window (bigger, sharper) qrcp --browser MyDocument.pdf
Hide the messages (the QR code is still printed) qrcp --quiet MyDocument.pdf

--reversed (-r) prints black on white, --browser (-b) opens the QR code as an image in your default browser, --quiet (-q) hides the messages, including the URL, and prints only errors and the QR code.


Receive files from your phone

qrcp receive                          # save to the current directory
qrcp receive --output ~/Downloads     # or -o: save to a specific directory
qrcp r -o ~/Downloads                 # same, with the short alias

Scanning the QR code opens an upload page on the phone, where you can:

Good to know:


Choose the network

The phone must reach the computer, so qrcp has to listen on the right network interface: usually your Wi-Fi or Ethernet one.

Network options

Goal Option Example
Use a specific interface --interface, -i qrcp -i wlan0 MyDocument.pdf
Listen on all interfaces (0.0.0.0) --interface any qrcp -i any MyDocument.pdf
Listen on a specific address (overrides the interface) --bind qrcp --bind 192.168.1.10 MyDocument.pdf
Use a fixed port, e.g. to open it in the firewall --port, -p qrcp -p 8080 MyDocument.pdf
Use a fixed URL path instead of a random one --path qrcp --path photos MyDocument.pdf
Put a host name in the URL instead of the IP address --fqdn, -d qrcp -d mypc.local MyDocument.pdf

Notes:


Secure transfers with HTTPS

By default the transfer uses plain HTTP inside your local network. To encrypt it, give qrcp a TLS certificate and key:

qrcp --secure --tls-cert ~/certs/cert.pem --tls-key ~/certs/key.pem MyDocument.pdf

--secure (-s) switches the URL to https://. The phone must trust the certificate, otherwise it shows a warning. The mkcert tutorial shows how to create a local certificate authority and a trusted certificate in a few minutes. Save the three settings with qrcp config to use HTTPS every time.


Troubleshooting

If the phone can’t open the URL, run:

qrcp doctor

It lists the network interfaces, marks the one that looks connected to the local network, and checks the port, the firewall, VPNs, WSL networking and, with --secure, the TLS certificate and key. Every problem comes with a suggested fix. Each check is reported as ok, info (couldn’t be fully checked), warn (likely to cause problems) or fail (transfers won’t work until it’s fixed).

qrcp doctor -i wlan0 -p 8080    # check a specific setup: it takes the same flags as send/receive
qrcp doctor --json              # machine-readable report, for scripts and AI agents

doctor only checks this computer: it can’t test the phone or the Wi-Fi network, so a clean report doesn’t guarantee the phone can connect. It never prompts and never changes the configuration. It exits with code 1 if a check fails. On Windows and macOS it only tries the port on 127.0.0.1, so the firewall doesn’t ask whether to allow qrcp.

The --json report has this shape:

{
  "failed": false,
  "checks": [{ "name": "…", "status": "ok|info|warn|fail", "message": "…", "hint": "…" }],
  "interfaces": [{ "name": "…", "ip": "…", "kind": "…" }],
  "suggested_interface": "…",
  "help_url": "…"
}

Common causes


Configuration

qrcp works without any configuration. Settings come from three places; the first one that sets a value wins:

  1. Command-line flags, e.g. --port 8080
  2. Environment variables, e.g. QRCP_PORT=8080
  3. The configuration file

Configuration file

The file is created automatically on the first run, in the qrcp folder of your user configuration directory:

System Default location
Linux $XDG_CONFIG_HOME/qrcp/config.yml (usually ~/.config/qrcp/config.yml)
macOS ~/Library/Application Support/qrcp/config.yml
Windows %LOCALAPPDATA%\qrcp\config.yml

Use another file with --config (-c). Its extension (.yml, .json…) tells qrcp the format:

qrcp --config ~/qrcp-work.yml MyDocument.pdf

Configuration wizard

qrcp config      # aliases: qrcp c, qrcp cfg

An interactive wizard that asks, in order, for: the network interface, the bind address, the port, the domain name, the URL path, keep-alive, HTTPS (and then the certificate and key), the default output directory for received files, and whether to reverse the QR code. It saves the answers in the configuration file.

Migrating from the old JSON format

Versions before 0.10 stored the configuration in config.json. qrcp still reads it, but you can convert it to YAML (and delete the old file) with:

qrcp config migrate

Options

Every option can be set in the file, as an environment variable, or as a flag:

Key in config.yml Environment variable Flag Type Description
interface QRCP_INTERFACE -i, --interface string Network interface to use. any listens on all interfaces (0.0.0.0).
bind QRCP_BIND --bind string Address to listen on. Overrides interface.
port QRCP_PORT -p, --port integer Port to use. 0 or unset means random.
path QRCP_PATH --path string URL path. Random by default.
fqdn QRCP_FQDN -d, --fqdn string Host name to put in the URL instead of the IP address.
keepAlive QRCP_KEEPALIVE -k, --keep-alive boolean Keep the server running after a transfer. Default false.
secure QRCP_SECURE -s, --secure boolean Use HTTPS. Requires tls-cert and tls-key.
tls-cert QRCP_TLS_CERT --tls-cert string Path to the TLS certificate.
tls-key QRCP_TLS_KEY --tls-key string Path to the TLS private key.
output QRCP_OUTPUT -o, --output string Default directory for received files.
reversed QRCP_REVERSED -r, --reversed boolean Print the QR code black on white.

Example config.yml:

interface: wlan0
port: 8080
keepAlive: false
output: /home/me/Downloads
secure: true
tls-cert: /home/me/certs/cert.pem
tls-key: /home/me/certs/key.pem

Command reference

Command Aliases Description
qrcp <file>...   Send files or folders (same as qrcp send).
qrcp send <file>... s Send files or folders.
qrcp receive r Receive files (and text) from the phone.
qrcp config c, cfg Run the configuration wizard.
qrcp config migrate   Convert the legacy config.json to config.yml.
qrcp doctor   Check why the phone can’t connect.
qrcp completion <shell>   Print a completion script for bash, zsh, fish or powershell.
qrcp version   Print the version and build information.
qrcp help [command]   Show help for any command. -h/--help works too.

Flags

These flags work with send, receive and doctor (and with every other command):

Flag Description
-i, --interface <name> Network interface to use (any for all interfaces).
-l, --list-all-interfaces Show all interfaces when choosing one, including virtual ones.
--bind <address> Address to listen on. Overrides --interface.
-p, --port <number> Port to use. Random by default.
--path <path> URL path. Random by default.
-d, --fqdn <name> Host name to use in the URL instead of the IP address.
-k, --keep-alive Keep the server running after a transfer.
-z, --zip Zip the content before sending, even a single file.
-s, --secure Use HTTPS.
--tls-cert <file> TLS certificate for HTTPS.
--tls-key <file> TLS private key for HTTPS.
-b, --browser Also show the QR code in a browser window.
-r, --reversed Print the QR code black on white.
-q, --quiet Hide messages; print only errors (and the QR code).
-c, --config <file> Use this configuration file.
-h, --help Show help.

Command-specific flags:

Command Flag Description
receive -o, --output <dir> Directory where received files are saved.
doctor --json Print the report as JSON.

Shell completion

qrcp can generate completion scripts for Bash, Zsh, Fish and PowerShell.

Shell Current session Every session (run once)
Bash source <(qrcp completion bash) Linux: qrcp completion bash > /etc/bash_completion.d/qrcp
macOS: qrcp completion bash > /usr/local/etc/bash_completion.d/qrcp
Zsh n/a qrcp completion zsh > "${fpath[1]}/_qrcp", then start a new shell
Fish qrcp completion fish | source qrcp completion fish > ~/.config/fish/completions/qrcp.fish
PowerShell qrcp completion powershell | Out-String | Invoke-Expression Add the same line to your PowerShell profile ($PROFILE)

For Zsh, completion must be enabled; if it isn’t, run echo "autoload -U compinit; compinit" >> ~/.zshrc once.


Credits

Similar projects

Project Description
qr-fileshare A similar idea executed in NodeJS with a React interface.
instant-file-transfer (Uncredited) Node.js project similar to this.
qr-filetransfer Python clone of this project.
qr-filetransfer Another Node.js clone of this project.
qr-transfer-node Another Node.js clone of this project.
QRDELIVER Node.js project similar to this.
qrfile Transfer files by scanning a QR code.
quick-transfer Node.js clone of this project.
share-file-qr Python re-implementation of this project.
share-files (Uncredited) Yet another Node.js clone of this project.
ezshare Another Node.js two-way file sharing tool supporting folders and multiple files.
local_file_share “Share local file to other people, OR smartphone download files which is in PC.”
qrcp A desktop app clone of qrcp, written with C# and .NET Core, works for Windows.
swift_file Rust project inspired by qrcp.
qrcp-android Android app inspired by qrcp.

License

qrcp is free and open-source software, released under the MIT license.