OnionOS Setup Guide for the Miyoo Mini Plus

The Miyoo Mini Plus ships with a stock firmware that mostly works but leaves a lot on the table — no RetroAchievements, a barebones game picker, and almost no customisation. OnionOS changes all of that. It’s the de facto standard for this device, to the point where community guides barely mention stock anymore. If you’ve just received your Mini Plus and want it to actually perform like the community says it should, this is the guide.

This walkthrough covers a clean OnionOS install from scratch: downloading the image, preparing your microSD, first boot, ROM organisation, and the first-hour tweaks that answer 90% of the questions in the forums.

What you’ll need

• Miyoo Mini Plus (OnionOS supports the Miyoo Mini, Miyoo Mini Plus, and Miyoo Mini v4 — no other hardware)
• microSD card — at least 16 GB; the community reports up to 512 GB working reliably. A Class 10 / A1-rated card is strongly recommended; slow cards cause stuttery loading
• SD card reader attached to your PC or Mac
• balenaEtcher or a file manager capable of extracting an archive to the card root
• ~20 minutes from download to first boot
• Risk level: low — the process is fully reversible by reflashing stock firmware

No soldering, no ADB, no unlocked bootloader. This is an SD-card swap, not a teardown.

Before you start

Back up anything on your existing SD card. If this is a new device, the stock card typically has a handful of built-in demo ROMs you won’t miss, but your BIOS files and any saves are worth keeping.

If something goes wrong after install — say, a black screen or boot loop — you can always reflash the original Miyoo stock firmware to the same card and start again. Community threads document this recovery path thoroughly.

Step 1: Download the firmware

Head to the official OnionOS releases page:

https://github.com/OnionUI/Onion/releases

Download the latest stable release (4.3 stable as of early 2026; a 4.4 beta is also available if you want cutting-edge features). GitHub shows SHA256 checksums alongside each release asset — verify the hash before you proceed. On Windows, certutil -hashfile filename.zip SHA256; on macOS/Linux, shasum -a 256 filename.zip.

Do not download from mirror sites or forum attachments. The GitHub releases page is the only authoritative source.

Step 2: Prepare the SD card

OnionOS distributes as a zip archive, not a raw disk image. That means you don’t flash it with Etcher — you extract it.

Format your microSD card as FAT32 (cards up to 32 GB) or exFAT (larger cards). Most cards come pre-formatted as exFAT; both work. On Windows, right-click the card in Explorer → Format. On macOS, use Disk Utility.

Once formatted, extract the contents of the OnionOS zip directly to the root of the card. You should see folders like App, Emu, RetroArch, BIOS, and a miyoo folder sitting at the top level — not inside a subfolder. This is the single most common setup mistake: extracting into a subdirectory rather than the root.

Step 3: Flash the image

Because OnionOS uses file extraction rather than a disk image, there’s no Etcher step here. Etcher is listed as an optional tool in the installation docs for users who prefer it with compatible builds, but the standard path is:

1. Format the card (Step 2)
2. Extract the OnionOS archive to the card root
3. Eject safely from your computer

That’s it. The Mini Plus handles the rest on first boot.

Step 4: First boot

Insert the prepared SD card into your Miyoo Mini Plus and power on. The first boot runs an installation sequence — expect the screen to go dark, reboot once or twice, and display progress text. This is normal. The full process takes about 2–3 minutes; don’t panic and don’t pull the card.

When the launcher appears, you’ll be prompted to select your language and a few basic preferences. After that, you land in the main menu.

A few things to check immediately:

• Wi-Fi: The Mini Plus has 2.4 GHz Wi-Fi. Go to Settings → Wi-Fi and connect to your network. This unlocks RetroAchievements login, the built-in scraper, and VNC remote control.
• Date/time: Set it correctly — RetroAchievements timestamps look odd if the clock is wrong.
• Brightness and sleep: OnionOS has a proper sleep mode; configure the timeout under Settings → Power.

Step 5: Add your games

OnionOS organises ROMs by a folder structure on the SD card. After first boot, the card gains a Roms directory with subfolders for each system — GBA, SFC, PS, NDS, and so on. Drop your ROMs into the matching folder and they appear in the launcher automatically.

BIOS files belong in the BIOS folder at the card root. PS1 requires BIOS files to boot most titles; GBA technically runs without one via the open-source BIOS in mGBA, but supplying the real GBA BIOS improves compatibility on a handful of titles. The OnionOS documentation lists the exact filenames and MD5 hashes required — match them precisely, as the emulators are filename-sensitive.

A few emulation reality checks for the Mini Plus hardware (SigmaStar SSD202D, 128 MB DDR3):

System	Expectation
NES, SNES, GBA, Game Boy	Runs perfectly
PS1	Runs perfectly; 5+ hours reported without hiccups
Nintendo DS	Runs via DraStic (added in OnionOS 4.3); light-to-medium titles work
N64	Not practical — hardware class and 128 MB RAM are limiting factors
Dreamcast	Do not attempt

Emulation performance on the Miyoo Mini Plus with OnionOS

• NES — various titles

  Full speed Perfect
• SNES — various titles

  Full speed Perfect
• GBA — various titles (mGBA)

  Full speed Perfect
• PS1 — various titles (PCSX ReARMed)

  Full speed Perfect
• Nintendo DS — light titles (DraStic)

  Playable, varies Playable
• N64

  Not practical Choppy

Common issues and fixes

Screen wobble on some units — a known hardware-level issue on a percentage of Mini Plus units, not firmware-related. The community fix is a small amount of B-7000 adhesive or double-sided foam tape between the screen bezel and the body. Documented in multiple community reviews.

DS games not appearing — Nintendo DS support was added in OnionOS 4.3 via native DraStic integration. If your install predates this, update to 4.3 or later. DS ROMs go in the NDS folder; DraStic requires a specific BIOS setup documented in the OnionOS wiki.

RetroAchievements not syncing — confirm Wi-Fi is connected and that you’ve entered your RA credentials under Settings → RetroAchievements. The device only connects on 2.4 GHz, so a 5 GHz-only network won’t work.

Black screen after swapping SD cards — ensure the card is formatted correctly and that the OnionOS files are at the root, not in a subfolder (see Step 2).

Performance tips

Activity tracker — OnionOS has a built-in activity tracker that logs playtime per game. Enable it in Settings. It’s a minor thing but genuinely useful if you juggle a large library and want to know what you’ve actually touched.

Quick game switching — OnionOS supports quick game switching between recently played titles. Once you’re comfortable with the menu, map it to a button combo; it makes the device feel much more responsive for library browsing.

Guest profile — 4.3 introduced a guest profile with independent favourites, recents, and theme. Useful if you share the device, or if you want a clean “show-off” profile with curated games separate from your main library.

VNC remote control — enable it under Apps. With VNC active, you can control the device from a PC browser or VNC client over Wi-Fi, which is practical during initial setup when you’re configuring cores and scraping artwork without wanting to navigate menus on a 3.5-inch screen.