PyFi 🚀

Fast, lightweight, zero-configuration local file sharing from your terminal to any device over Wi-Fi.

PyFi (Python + File / Wi-Fi) lets you instantly share files between your computer and mobile phone (iOS / Android) or other computers on the same local network by simply scanning a QR code in your terminal.

---

---

✨ Features

• ⚡ Ultra-Fast Streaming: Pure standard-library multi-threaded socket streaming (no heavy Flask/Gunicorn runtime).
• 📱 Camera-Ready QR Code: High-contrast, compact terminal QR code for instant scanning with the iOS Camera app or Google Lens.
• 📊 Live Dynamic Progress Bar: Real-time single-line terminal progress bar tracking %, transferred MB, speed in MB/s, and auto-adjusting ETA.
• ⏩ HTTP Range Requests (206 Partial Content): Supports paused download resumption and multi-chunk mobile download accelerators.
• 🚪 Clean Auto-Exit: Automatically shuts down and exits cleanly back to your shell prompt as soon as the transfer finishes.
• 🪶 Minimal Dependencies: Standalone lightweight package with zero bloated web framework dependencies.

---

⚡ Quick Start

Installation

Option 1: Prebuilt Standalone Binary (Recommended)

Download the latest standalone binary from the GitHub Releases page:

Linux / macOS:

# Extract the archive
tar -xzf pyfi-linux-x86_64.tar.gz   # (or pyfi-macos-arm64.tar.gz)

# Move binary to PATH and set permissions
sudo mv pyfi /usr/local/bin/
sudo chmod +x /usr/local/bin/pyfi

# macOS: If Gatekeeper shows an unverified developer warning:
xattr -d com.apple.quarantine /usr/local/bin/pyfi

Windows: Download pyfi-windows-x64.zip, extract pyfi.exe, and run it directly or add it to your system PATH.

---

Option 2: Install via pip

pip install pyfi-share

---

Option 3: Install from Source

# Clone the repository
git clone https://github.com/vubon/pyfi.git
cd pyfi

# Install in editable mode
pip install -e .

Usage

Share any file by passing its name or path:

# 1. Using the pyfi command:
pyfi video.mp4

# 2. Or using the Python module:
python -m PyFi video.mp4

1. Run the command in your terminal.
2. Open your phone's native Camera app and point it at the terminal QR code.
3. Tap the prompt to download the file directly to your device!

---

🚀 Maximizing Transfer Speed (Tx Rate & Wi-Fi Guide)

To achieve maximum download speeds (e.g. 20 – 50+ MB/s):

1. Connect Both Devices to 5 GHz or Wi-Fi 6

• 5 GHz / Wi-Fi 6 (802.11ax / 802.11ac) provides wider bandwidth channels and high Tx Rates (500 Mbps – 1200+ Mbps), allowing multi-gigabyte files to transfer in seconds.
• Avoid 2.4 GHz networks: 2.4 GHz Wi-Fi is crowded with high interference and low Tx Rates (often limited to 54–144 Mbps), resulting in slower transfers (~2–4 MB/s).

2. Check Your Mac's Wi-Fi Tx Rate

Hold Option (⌥) and click the Wi-Fi icon in your macOS menu bar:

• Tx Rate > 500 Mbps: Ideal for high-speed file transfers.
• Tx Rate < 150 Mbps: Check router distance or switch your Wi-Fi network to the 5 GHz band.

3. 💡 Pro-Tip: Direct Phone Hotspot (P2P Wi-Fi)

When both sender and receiver are connected through a home router, Wi-Fi airtime is shared (half-duplex relay). For maximum speed on the go:

1. Turn on your Phone's Personal Hotspot (enable Maximize Compatibility / 5GHz).
2. Connect your Mac to the phone's Hotspot.
3. Run pyfi <file> — this establishes a direct point-to-point Wi-Fi link for maximum transfer rates!

---

🛠️ Developer & Makefile Commands

PyFi includes a handy Makefile for common tasks:

Command	Action
make test	Run the complete unit test suite (tests/test_pyfi.py)
make run FILE=video.mp4	Run PyFi with a specified file
make install	Install PyFi in editable development mode
make build	Build source distribution and .whl package
make binary	Package a standalone executable with PyInstaller
make clean	Remove temporary cache and build artifacts

---

📄 License

This project is licensed under the MIT License.