qrcp: The QR Code File Transfer Tool

Transfer files instantly between your computer and mobile device using nothing but QR codes and your terminal. No cables, no cloud, no hassle.

Tired of fumbling with USB cables? Fed up with uploading sensitive files to cloud services just to download them again on your phone? qrcp eliminates these friction points completely. This sleek Go-powered utility transforms your terminal into a wireless file transfer powerhouse. In this deep dive, you'll discover how qrcp works under the hood, master its advanced configuration options, and learn why developers worldwide are adding it to their essential toolkit.

What Is qrcp and Why Developers Can't Stop Talking About It

qrcp is a lightning-fast command-line tool that transfers files over Wi-Fi by generating QR codes you scan with your mobile device. Created by Claudio d'Angelis, this open-source project has captured the developer community's attention for its elegant simplicity and remarkable efficiency.

The magic happens through a clever combination of technologies. When you execute a qrcp command, the tool binds a web server to your Wi-Fi network interface on a random port. It then generates a unique URL containing a random path and encodes this URL into a QR code displayed directly in your terminal. Your mobile device's QR scanner detects the URL and automatically launches the browser, initiating the file transfer.

What makes qrcp genuinely revolutionary is its bi-directional capability. Unlike most transfer tools that only send files from computer to mobile, qrcp can receive files too. When receiving, it serves an upload page to your mobile browser, allowing you to select and send multiple files back to your computer. This two-way street transforms how developers, designers, and power users move data between devices.

The project has gained massive traction because it solves a universal pain point with zero configuration required. No accounts, no subscriptions, no third-party servers. Your data stays on your local network. The repository boasts thousands of stars, and the active Telegram channel qrcp_dev buzzes with feature discussions and user testimonials.

Key Features That Make qrcp Essential

Zero-Configuration Operation

qrcp works out of the box with sensible defaults. No editing config files or wrestling with network settings. Install it, run it, and start transferring files within seconds. The tool automatically detects your network interface and assigns a random port, eliminating conflicts and manual setup.

Bi-Directional File Transfer

Send files from computer to mobile or receive files from mobile to computer. This dual capability sets qrcp apart from simplistic HTTP servers or single-purpose transfer apps. The receive mode serves a clean upload interface optimized for mobile browsers.

Intelligent File Handling

Send single files, multiple files, or entire folders with a single command. qrcp automatically compresses folders into zip archives before transfer. The --zip flag lets you compress individual files on the fly, perfect for large videos or batches of images.

Advanced Network Control

Specify exact network interfaces with the -i flag or bind to all interfaces with -i any. This granularity proves invaluable for developers working with VPNs, virtual machines, or complex network setups. The bind configuration option even lets you override interface selection entirely.

Enterprise-Grade Security

Enable HTTPS transfers with custom TLS certificates. The secure configuration option encrypts your transfers, crucial for sensitive documents or corporate environments. Combined with random path generation, this creates secure, short-lived endpoints that are nearly impossible to guess.

Flexible Configuration System

Customize behavior through YAML configuration files or environment variables. The $XDG_CONFIG_HOME/qrcp/config.yml file supports all options, while QRCP_* environment variables provide per-session overrides. This dual approach suits both permanent preferences and temporary needs.

Shell Integration Excellence

Native shell completion for Bash, Zsh, and Fish. Generate completion scripts instantly and enjoy tab-completion for commands, flags, and file paths. This attention to developer experience demonstrates the project's maturity.

Cross-Platform Pervasiveness

Available on Linux, macOS, and Windows through multiple distribution channels. Install via Homebrew, WinGet, Scoop, Chocolatey, AUR, or direct binaries. The Go-based binary runs anywhere without dependencies.

Real-World Use Cases Where qrcp Shines

1. Mobile Developer Workflow Acceleration

You're building a React Native app. The APK is ready for testing, but emailing it to yourself feels archaic. qrcp app-debug.apk generates a QR code. Scan it with your test device, and the app installs instantly. No USB debugging, no cable hunting. The random URL path prevents unauthorized downloads, and the server shuts down automatically after transfer.

2. Designer Client Presentations

Your design team just finished mockups for a client review. Instead of uploading to Dropbox and waiting for sync, qrcp --zip Design-Mockups/ creates a compressed archive and QR code. The client scans it during your video call and receives the files while you watch. The transfer happens over your local network, keeping large files off public cloud servers.

3. Conference and Classroom Content Distribution

You're presenting at a tech conference and want to share slides and code samples. Rather than dealing with spotty conference Wi-Fi and USB drives, qrcp -i any --keep-alive Presentation.pdf Code-Samples.zip binds to all interfaces and stays alive. Audience members scan the QR code projected on screen and download materials directly. The --keep-alive flag maintains the server for latecomers.

4. System Administrator Emergency File Access

A server is down, and you need logs immediately. You're on-call with only your phone. SSH into the server, run qrcp receive --output=/var/logs, and scan the QR code. Your phone's browser opens an upload page. Select the diagnostic files from your device and send them directly to the server. No intermediate steps, no security risks from temporary cloud storage.

5. Secure Document Transfer in Corporate Environments

You're handling confidential financial reports that can't touch external services. qrcp --secure --tls-cert /etc/ssl/corp.crt --tls-key /etc/ssl/corp.key Q4-Report.pdf creates an HTTPS endpoint on your secure internal network. The QR code encodes an HTTPS URL, ensuring encryption in transit. The random path and automatic server shutdown minimize exposure windows.

Step-by-Step Installation & Setup Guide

Method 1: Install with Go (Latest Development Version)

For developers who want the bleeding-edge version:

# Requires Go 1.18 or later
go install github.com/claudiodangelis/qrcp@latest

This command fetches, builds, and installs the latest commit directly from the main branch. Perfect for accessing features before official releases.

Method 2: macOS with Homebrew

The simplest method for Mac users:

brew install qrcp

Homebrew handles dependencies, updates, and PATH configuration automatically. Run brew upgrade qrcp to stay current.

Method 3: Windows with WinGet

For Windows 10/11 users with the App Installer:

winget install --id=claudiodangelis.qrcp -e

The -e flag ensures exact package matching. WinGet manages updates through the Microsoft Store infrastructure.

Method 4: Linux Package Managers

Arch Linux (AUR):

yay -S qrcp-bin  # Prebuilt binary
# or
yay -S qrcp      # Build from source

Debian/Ubuntu: Download the .deb file from Releases and install:

sudo dpkg -i qrcp_0.10.1_linux_x86_64.deb

CentOS/Fedora:

sudo rpm -i qrcp_0.10.1_linux_x86_64.rpm

Method 5: Manual Binary Installation

For maximum control or unsupported systems:

# Download the latest release for your platform
curl -L -o qrcp.tar.gz https://github.com/claudiodangelis/qrcp/releases/latest/download/qrcp_0.10.1_linux_x86_64.tar.gz

# Extract
tar -xzf qrcp.tar.gz

# Move to system PATH
sudo mv qrcp /usr/local/bin/

# Set executable permission
sudo chmod +x /usr/local/bin/qrcp

Verify Installation

Confirm everything works:

qrcp --help

You should see the help menu with available commands and flags. If you get a "command not found" error, check your PATH:

# Check if qrcp is in PATH
which qrcp

# On Linux/macOS, ensure /usr/local/bin is in PATH
echo $PATH

REAL Code Examples from the Repository

Example 1: Sending a Single File

The most common operation - transferring a document to your phone:

# Send a PDF document to your mobile device
qrcp MyDocument.pdf

What happens behind the scenes:

1. qrcp detects your active Wi-Fi interface (e.g., wlan0 with IP 192.168.1.100)
2. Binds an HTTP server to a random available port (e.g., 43210)
3. Generates a cryptographically random path (e.g., xY9zK8vN7)
4. Constructs the URL: http://192.168.1.100:43210/xY9zK8vN7
5. Displays a QR code in your terminal encoding this URL
6. Serves the file when your mobile browser requests it
7. Automatically exits after successful transfer

The beauty lies in its ephemeral nature. The server exists only for this transfer, reducing security exposure. The random path prevents URL guessing attacks.

Example 2: Receiving Files to a Specific Directory

Transfer photos from your phone to a project folder:

# Receive files directly into your project's assets directory
qrcp receive --output=~/Projects/MyApp/assets/

Technical breakdown:

• The receive command switches qrcp into upload mode
• --output (or -o) specifies the destination directory
• qrcp serves an HTML upload page optimized for mobile browsers
• The page uses multipart/form-data POST requests to handle file uploads
• Multiple files can be selected and uploaded simultaneously
• Files are written to the specified directory with original filenames
• The server stays alive until you press Ctrl+C

This is perfect for content creators who shoot photos on mobile but edit on desktop. No more emailing yourself or using cloud sync services.

Example 3: Network Interface Selection with VPN

You're connected to both Wi-Fi and a corporate VPN. qrcp needs to use the Wi-Fi interface:

# Force qrcp to use the Wi-Fi interface (replace wlan0 with your interface name)
qrcp -i wlan0 LargeVideo.mp4

# Or bind to all interfaces if you're unsure
qrcp -i any Presentation.pptx

Deep dive into networking: The -i flag accepts interface names (wlan0, eth0, tun0) or special values:

• any binds to 0.0.0.0, listening on all available interfaces
• This is crucial when your machine has multiple network connections
• The tool automatically selects the first non-loopback interface if unspecified
• You can also use the --bind flag to specify an exact IP address:

  qrcp --bind 192.168.1.50 DesignFiles.zip
  

For VPN users, explicitly specifying the Wi-Fi interface ensures the QR code contains a reachable IP address rather than the VPN's internal IP.

Example 4: Secure HTTPS Transfers

Transfer sensitive financial data with encryption:

# Enable HTTPS with your TLS certificate and key
qrcp --tls-cert /path/to/cert.pem --tls-key /path/to/cert.key Confidential.pdf

Security implementation details:

• The --secure flag (or secure: true in config) enables HTTPS mode
• --tls-cert and --tls-key provide the cryptographic materials
• qrcp uses Go's standard crypto/tls library for robust encryption
• The QR code encodes an https:// URL instead of http://
• TLS 1.2+ is enforced with modern cipher suites
• Perfect for HIPAA compliance, financial data, or corporate secrets

Generate a self-signed certificate for testing:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Example 5: Configuration File Customization

Create a persistent configuration for your workflow:

# Use a custom config file for a specific project
qrcp --config ~/Projects/SecureTransfer/qrcp.yml ConfidentialData.zip

Configuration file structure (qrcp.yml):

# Network interface to bind (any, wlan0, eth0, etc.)
interface: wlan0

# Fixed port instead of random (useful for firewall rules)
port: 8080

# Custom path instead of random string
path: transfer

# Default receive directory
output: ~/Downloads/qrcp

# Keep server alive after transfer
keep-alive: true

# Enable HTTPS by default
secure: true
tls-cert: /home/user/.certs/server.crt
tls-key: /home/user/.certs/server.key

# Use a custom domain instead of IP
fqdn: transfer.mycompany.local

Environment variable alternative:

export QRCP_INTERFACE=wlan0
export QRCP_PORT=8080
export QRCP_OUTPUT=~/Downloads/qrcp
export QRCP_SECURE=true

This flexibility lets you create project-specific configurations. A photographer might set output to a photos directory, while a developer might enable keep-alive for continuous testing.

Advanced Usage & Best Practices

Persistent Server Mode for Multiple Transfers

By default, qrcp exits after one transfer. For presentations or workshops:

qrcp --keep-alive --path workshop Materials.zip

The server remains active, and the same QR code works for multiple recipients. Press Ctrl+C when finished.

Integration with Build Scripts

Add qrcp to your CI/CD pipeline for mobile app distribution:

#!/bin/bash
# Build and send APK to QA team
./gradlew assembleDebug
qrcp --keep-alive --port 9000 app/build/outputs/apk/debug/app-debug.apk
echo "Scan the QR code to download the test build"

Firewall-Friendly Operation

Specify a fixed port for corporate firewall rules:

qrcp --port 8080 --fqdn files.corp.local Document.pdf

Your firewall admin can open TCP 8080, and the FQDN ensures the QR code shows a proper hostname instead of IP.

Security Hardening

For maximum security in sensitive environments:

1. Always use HTTPS with valid certificates
2. Set a custom path instead of random (better for auditing)
3. Use --bind to restrict to specific IP addresses
4. Monitor access logs (future feature in development)
5. Combine with VPN for remote access scenarios

Automation with Aliases

Create shell aliases for common workflows:

# In ~/.bashrc or ~/.zshrc
alias qsend='qrcp --zip'
alias qrecv='qrcp receive --output=~/Downloads'
alias qshare='qrcp --keep-alive --port 8080'

Comparison with Alternatives

Why qrcp wins for developers:

• Terminal-native workflow - no leaving your command line
• Scriptable - integrate into build processes
• Ephemeral - servers auto-shut down, reducing attack surface
• Network-aware - handles complex multi-interface setups
• Lightweight - single binary, minimal resource usage

AirDrop is seamless but locks you into Apple's ecosystem. Python's http.server is universal but clunky and insecure. Snapdrop is convenient but requires internet connectivity. qrcp hits the sweet spot of simplicity, security, and control.

Frequently Asked Questions

Q: Is qrcp secure for transferring sensitive files? A: Yes, when using the --secure flag with TLS certificates. For maximum security, generate self-signed certificates or use your organization's PKI. The ephemeral nature (auto-shutdown) and random paths provide additional protection.

Q: What's the maximum file size I can transfer? A: There's no built-in limit. Transfer size depends on your network stability and device storage. For multi-gigabyte files, use the --zip flag to compress and consider a wired connection for reliability.

Q: Does qrcp require internet access? A: No. qrcp works entirely on your local network (LAN). Both devices must be on the same Wi-Fi network. No data leaves your premises, making it perfect for air-gapped or secure environments.

Q: How is qrcp different from python -m http.server? A: qrcp offers QR code generation, automatic interface detection, bi-directional transfers, HTTPS support, and mobile-optimized UI. Python's server requires manual URL entry, only sends files, and serves over unencrypted HTTP.

Q: Can I customize the QR code or add branding? A: Currently, qrcp generates standard QR codes in the terminal. For custom branding, you could fork the repository and modify the QR generation logic in the server package. The project welcomes contributions.

Q: Why can't my phone connect after scanning? A: Common issues: devices not on same network, firewall blocking the port, or VPN interference. Try qrcp -i any to bind all interfaces, and check your phone's Wi-Fi connection. Corporate networks may block device-to-device communication.

Q: Is qrcp available for Android or iOS as a mobile app? A: No, and that's intentional. qrcp leverages your mobile device's existing QR scanner and web browser. This eliminates app installation, reduces attack surface, and ensures universal compatibility across all modern smartphones.

Conclusion: Transform Your File Transfer Workflow Today

qrcp represents the pinnacle of developer-focused tooling - it solves a universal problem with breathtaking simplicity while offering depth for power users. The zero-configuration approach gets you started in seconds, but the advanced features like HTTPS, custom interfaces, and configuration files make it enterprise-ready.

The project's active development, responsive maintainer, and vibrant community signal long-term viability. Whether you're a mobile developer pushing test builds, a designer sharing mockups, or a sysadmin managing servers, qrcp deserves a permanent spot in your terminal toolkit.

Don't wait - install qrcp now and experience frictionless file transfers. Star the repository at github.com/claudiodangelis/qrcp to support the project and get updates. Join the Telegram channel to connect with fellow users and contribute to the roadmap.

Your future self will thank you every time you avoid the USB cable dance or the "email it to myself" anti-pattern. One command, one QR code, infinite possibilities.