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:

📄 License

This project is licensed under the MIT License.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.1.1] - 2026-08-22

Added

• Automated PyPI Publishing: Connected GitHub Actions release.yml with PyPI to automatically publish .whl and .tar.gz packages on git tag releases.
• Package Manifest (MANIFEST.in): Added manifest template ensuring all markdown documentation, licenses, and media assets are included in the source distribution.

Fixed

• Fixed sdist packaging issue when building wheel distributions from source.

[0.1.0] - 2026-08-22

Added

• High-Performance HTTP Streaming: Implemented lightweight, multi-threaded socket streaming server using Python's standard library (http.server & socketserver.ThreadingMixIn).
• HTTP Range Request Support (206 Partial Content): Added full support for Range: bytes=start-end headers, enabling resumable downloads and multi-threaded mobile download accelerators.
• Real-Time Live Progress Bar: Added smooth, single-line terminal progress bar tracking completion percentage, data transferred/total size, real-time speed in MB/s, and smart ETA.
• Smart Duration Formatting: Formats elapsed time and ETA dynamically in seconds (s), minutes (m), or hours (h).
• Dynamic Terminal Width Detection: Automatically calculates terminal column width (shutil.get_terminal_size) to prevent text wrapping on narrow terminal panes.
• Framed Terminal Card: Displays high-contrast QR code (border=2) within an elegant box border matching terminal themes.
• Automated Server Auto-Exit: Automatically shuts down and returns to the shell prompt once the file transfer is complete.
• Flexible Path Resolution: Supports absolute paths (/), relative paths (./), and user home shortcuts (~/) from any directory.
• Fast Standalone Binary (zipapp): Package standalone single-file executables with instant (~0.08s) startup time and ~640 KB footprint.
• Automated CI/CD: Added GitHub Actions workflows for multi-version testing (ci.yml) and automated cross-platform binary releases on git tags (release.yml).
• Developer Makefile: Added developer shortcuts for make install, make test, make run, make build, make binary, and make clean.
• Unit Test Suite: Created automated test suite (tests/test_pyfi.py) covering full streaming, range slicing, 404 handling, auto-exit, and formatting utilities.

Changed

• Removed heavy external web framework dependencies (Flask, Werkzeug, Gunicorn) in favor of Python standard library.
• Refactored project architecture to follow standard Python separation of concerns (PyFi/utils/util.py for helpers and PyFi/server/server.py for networking).
• Made terminal logs quiet by default, adding -d / --debug flag for low-level connection inspection.
• Updated documentation and README with Wi-Fi 5 GHz / Tx Rate optimization guide.

Fixed

• Fixed macOS socket truncation issue when streaming large files.
• Fixed runpy module collision runtime warning during CLI module invocation.
• Fixed socket handling to gracefully handle client disconnections (ConnectionResetError, BrokenPipeError) from mobile browsers.

[0.0.1-alpha] - 2026-07-20

Added

• Initial project prototype for sharing files over local Wi-Fi with QR code generation.