📖 Overvieww
MiFlasher is a fully open-source command-line toolkit and web GUI for managing Xiaomi/MIUI devices from Termux on Android. No PC required for most operations.
Built for power users, developers, and ROM flashers who want a professional, scriptable tool — not a bloated Windows-only GUI.
Example:
$ ./miflasher device
Device Information
+-----------------+--------------------------------+
| Property | Value |
+-----------------+--------------------------------+
| Serial | 1a2b3c4d |
| Mode | ADB |
| Brand | Xiaomi |
| Model | Redmi Note 12 Pro |
| Codename | ruby |
| Android Version | 13 |
| MIUI Version | MIUI 14.0.6 |
| RAM | 5824 MB free / 8192 MB total |
| Bootloader | yes (unlocked) |
| Battery | 87% (Charging) |
+-----------------+--------------------------------+
✨ Features
🔧 Device Management
- Full device info: model, RAM, storage, battery, display, security patch, slot, kernel
- Real-time device watch mode (
--watch)
- Reboot to any mode: System, Bootloader, Recovery, Fastbootd, EDL
⚡ Flashing
- Flash full ROM packages (ZIP / TGZ / TAR.GZ)
- Flash individual images: boot, recovery, vbmeta, super
- Flash OTA packages via
payload.bin
- A/B slot support (flash to slot A, B, or both)
- Auto-detect and run Xiaomi flash scripts (
flash_all.sh, etc.)
🔓 Bootloader Unlock
- Browser-based Mi Account login flow (no PC needed)
- Session token extraction from redirect URL
- Guided step-by-step unlock instructions
- Direct fastboot unlock (
--fastboot-only) for already-authorized devices
💾 Backup & Restore
- Backup any/all partitions via
fastboot fetch or ADB
- Optional GZIP compression of backup archives
- Full restore from backup directory or
.tar.gz
- Smart per-partition status reporting
🌐 Web GUI
- Full single-page dashboard at
http://localhost:8080
- Real-time device polling (auto-refreshes every 5s)
- Flash, wipe, backup, unlock — all from browser
- Session log viewer
- Dark theme, responsive layout
📋 Logging & Sessions
- Leveled colored logging: DEBUG / INFO / SUCCESS / WARNING / ERROR / CRITICAL
- Every session saved to
~/.local/share/miflasher/logs/ as JSONL
- View, tail, filter, and clear logs via
miflasher logs
⚙️ Configuration
- Persistent JSON config at
~/.config/miflasher/config.json
- Set download dir, backup dir, auto-verify, GUI port, and more
- Per-command overrides via flags
📋 Requirements if run Android/Termux
| Requirement |
Notes |
| Android |
9+ (API 28+) |
| Termux |
Latest from F-Droid recommended |
| Python |
3.10 or newer |
| android-tools |
Provides adb and fastboot |
| USB OTG |
For ADB/Fastboot device connection |
| Mi Account |
For bootloader unlock authorization |
⚠️ Note: Do NOT install Termux from the Play Store — use F-Droid for the latest version.
🚀 Installation
Quick Install (Recommended)
# 1. Clone the repo
git clone https://github.com/djunekz/miflasher
cd miflasher
# 2. Run installer
bash install.sh
# 3. Reload shell
source ~/.bashrc
# 4. Test
miflasher --version
Manual Install
# Install system dependencies
pkg update && pkg install python android-tools pv
# Install Python dependencies
pip install requests --break-system-packages
# Make executable and symlink
chmod +x miflasher
ln -sf "$(pwd)/miflasher" ~/.local/bin/miflasher
# Grant storage access
termux-setup-storage
Verify Installation
miflasher --version
miflasher --help
📚 Commands
miflasher device
miflasher device # Show device info table
miflasher device --watch # Live device monitor
miflasher device --json # Output as JSON (for scripting)
miflasher device --reboot bootloader # Reboot to specific mode
Reboot modes: system bootloader recovery fastbootd edl
miflasher unlock
miflasher unlock # Mi Account login + guided unlock
miflasher unlock --force # Skip confirmation prompt
miflasher unlock --fastboot-only # Direct fastboot unlock (USB required)
miflasher unlock --token TOKEN # Use pre-obtained token
Unlock flow:
- Tool displays Mi Account login URL
- Log in via your phone browser
- Browser redirects → copy the URL from address bar
- Paste into terminal → tool verifies session
- Follow the displayed fastboot instructions
miflasher flash
# ROM (auto-runs flash_all.sh or flashes all .img files)
miflasher flash rom --path /sdcard/Download/miui_rom.zip
miflasher flash rom --url https://bigota.d.miui.com/.../miui_rom.tgz
miflasher flash rom --path rom.zip --keep-data # Preserve /data
# Boot image (Magisk, patched boot, etc.)
miflasher flash boot --path boot.img
miflasher flash boot --path boot.img --slot a # Flash to slot A only
# Other images
miflasher flash recovery --path recovery.img
miflasher flash vbmeta --path vbmeta.img
miflasher flash super --path super.img
miflasher flash payload --path payload.bin
# Shared flags
--slot [a|b|all] # Target slot (default: all)
--skip-verify # Skip checksum verification
--no-reboot # Do not reboot after flash
--wipe-data # Wipe /data after flash
miflasher backup
miflasher backup --all # Backup all known partitions
miflasher backup --partition boot recovery # Backup specific partitions
miflasher backup --all --compress # Compress to .tar.gz
miflasher backup --all --out /sdcard/mybackups # Custom output directory
miflasher restore
miflasher restore --path /sdcard/MiFlasher/backups/backup_20250101
miflasher restore --path backup.tar.gz
miflasher restore --path backup/ --partition boot vbmeta # Selective restore
miflasher wipe
miflasher wipe --data # Wipe /data (factory reset)
miflasher wipe --cache # Wipe cache partition
miflasher wipe --dalvik # Wipe Dalvik/ART cache
miflasher wipe --all # Wipe data + cache + dalvik
miflasher wipe --all --force # Skip confirmation
miflasher logs
miflasher logs # Show last 50 log lines
miflasher logs --tail 100 # Show last 100 lines
miflasher logs --list # List all saved sessions
miflasher logs --session 20250101_130000 # View specific session
miflasher logs --clear # Delete all logs
miflasher gui
miflasher gui # Start at http://localhost:8080 (open the full URL with #token=... printed in the terminal)
miflasher gui --port 9090 # Custom port
miflasher gui --no-browser # Don't auto-open browser
miflasher gui --host 0.0.0.0 # Accessible from other devices on network
miflasher config
miflasher config --show # Show all config values
miflasher config --get theme # Get single value
miflasher config --set theme=dark auto_verify=true
miflasher config --reset # Reset to defaults
🗂️ Project Structure
miflasher/
├── miflasher # Main CLI entry point (executable)
├── install.sh # Termux auto-installer
├── requirements.txt # Python dependencies
│
├── core/ # Core modules
│ ├── banner.py # ASCII art banner
│ ├── logger.py # Rich colored logger, progress bar, tables
│ ├── device.py # ADB/Fastboot device detection & info
│ ├── flash.py # Flash manager (ROM, boot, payload, etc.)
│ ├── downloader.py # Resumable downloader with checksum verify
│ ├── unlock.py # Bootloader unlock manager
│ ├── backup.py # Partition backup & restore
│ ├── wipe.py # Partition wipe manager
│ ├── config.py # Persistent configuration
│ └── session.py # Session log management
│
├── modules/ # Plugin-style modules
│ └── miunlock_wrapper.py # Mi Account unlock flow
│
├── gui/ # Web dashboard
│ └── app.py # Single-file SPA (HTML + CSS + JS + API)
│
Documentation
├── README.md
├── CONTRIBUTING.md
├── SECURITY.md
└── CODE_OF_CONDUCT.md and etc docs
⚙️ Configuration Reference
Config file: ~/.config/miflasher/config.json
| Key |
Default |
Description |
theme |
dark |
CLI/GUI theme |
download_dir |
~/storage/downloads/MiFlasher |
ROM download directory |
backup_dir |
~/storage/downloads/MiFlasher/backups |
Partition backup directory |
log_dir |
~/.local/share/miflasher/logs |
Session log directory |
auto_verify |
true |
Auto checksum-verify downloads |
auto_reboot |
true |
Auto-reboot device after flash |
slot |
all |
Default flash slot (a/b/all) |
gui_port |
8080 |
Web GUI port |
gui_host |
localhost |
Web GUI host |
verbose |
false |
Enable debug logging |
❓ FAQ
Do I need root to use MiFlasher?
No. MiFlasher uses standard adb and fastboot — no root required. Some features (like reading /dev/block/ partitions for backup) may work better with root, but it is never required.
Why does miflasher device show "USB-UNKNOWN"?
This means termux-usb detected a USB device, but ADB and Fastboot didn’t respond. Common causes:
- USB Debugging not enabled → Settings → Developer Options → USB Debugging
- ADB server not running →
adb kill-server && adb start-server
- Device shows “Unauthorized” → tap Allow on device screen
- Wrong USB mode → use “File Transfer” (MTP) mode, not “Charging only”
Can I unlock the bootloader without a Windows PC?
Partially. MiFlasher handles the Mi Account authentication entirely from your phone (browser login). However, the final fastboot unlock step still requires a USB connection to execute fastboot flashing unlock. You do NOT need a separate PC — you can use miflasher unlock --fastboot-only from Termux itself.
Why does the Xiaomi unlock API return empty responses?
Xiaomi’s unlock API (unlock.update.miui.com) uses proprietary HMAC signatures generated by their official Windows tool using a hardcoded secret key. This key is not publicly available, so direct API calls cannot be properly signed and the server returns empty/error responses. MiFlasher handles everything that can be done without that key.
My device is A/B (VAB). How do slots work?
A/B devices have two copies of partitions (slot_a and slot_b). MiFlasher defaults to flashing both (--slot all). If you want to flash to a specific slot only, use --slot a or --slot b. After flashing, the device boots from the updated slot.
Flash failed with "No device in fastboot mode". What do I do?
- Make sure device is in fastboot mode: hold Vol- + Power for ~10 seconds until Fastboot screen appears
- Connect USB cable
- Run
fastboot devices — device should appear
- Retry:
miflasher flash boot --path boot.img
If fastboot devices is empty even with device showing Fastboot screen, try a different USB cable or USB OTG adapter.
How do I flash Magisk?
- Download Magisk APK from Magisk releases
- In Magisk app: Install → Select and Patch a File → pick your
boot.img
- Magisk saves
magisk_patched_XXXXX.img to /sdcard/Download/
- Flash it:
miflasher flash boot --path /sdcard/Download/magisk_patched_XXXXX.img
- Reboot:
miflasher device --reboot system
🛡️ Safety & Disclaimers
USE AT YOUR OWN RISK.
- Flashing incorrect ROMs or images can brick your device
- Bootloader unlock permanently wipes all user data
- Always backup important data before any flash/unlock operation
- Verify ROM checksums before flashing
- This tool is provided as-is, without warranty of any kind
See SECURITY.md for vulnerability reporting and LICENSE for full terms.
🤝 Contributingg
We welcome contributions of all kinds — bug fixes, new features, documentation improvements, and translations.
See CONTRIBUTING.md for:
- How to set up a development environment
- Coding standards and style guide
- How to submit pull requests
- Issue reporting guidelines
📄 License
MIT License
Full license: LICENSE
Use-at-your-own-risk notice and trademark statement: DISCLAIMER.md
🙏 Acknowledgements
- Termux — the Android terminal that makes this possible
- android-tools — ADB and Fastboot
- miunlock — original Mi unlock inspiration
- Magisk — root solution for Xiaomi devices
- All contributors and testers in the community
Made with love for the Android modding community
⭐ Star this repo if MiFlasher helped you!
评论