Installing ROCKNIX step by step: the complete guide

ROCKNIX is a Linux distribution built for retro gaming handhelds. It replaces the factory firmware and brings a unified interface, up-to-date emulators and very broad hardware coverage: Anbernic, Powkiddy, Ayn, Retroid, AYANEO, GameForce, Hardkernel, MagicX and several unbranded clones. The project is a fork of JELOS, whose code it took over after that project was discontinued.

Installation isn't complicated, but one step trips up a lot of people on their first attempt: on Allwinner H700 machines, you have to copy a device tree file yourself before the very first boot. Here's the procedure, checked against the project's official documentation in August 2026.

Who ROCKNIX is for

The developers are clear: the project is supplied “as is”, with no formal support, and describes itself as a tinkerer's distribution. No guarantee that it will work, and documentation that is still a work in progress in places.

So ROCKNIX suits you if you're willing to read a wiki page, compare a model number and redo a step when it fails. Otherwise the original firmware already does the job, and our product pages state the condition each console ships in — ready to play, or to be set up.

Our general guide to custom firmware compares muOS, Knulli, ArkOS, ROCKNIX and Batocera. This article covers ROCKNIX only.

Which machines in our range are supported

Hardware coverage is one of the project's strengths: the official list runs to more than sixty machines. Here's where the consoles we sell stand.

x86 images also exist for Windows handhelds. Check the up-to-date list on the project's Devices page, together with our firmware compatibility table.

What ROCKNIX brings over the original firmware

A single interface for everything. ROCKNIX uses EmulationStation, with a built-in scraper for box art, themes, collections, shaders and overlays. Anbernic's factory firmware, by contrast, mixes several interfaces depending on the system emulated.

Regular updates. Since the start of 2026, the project has released an image on the first day of each month: 20260601, 20260701, 20260801. The pace was more irregular before that. The most recent version as we write is 20260801.

Networking and online services. Wi-Fi, Samba sharing, SSH, netplay, RetroAchievements and cloud save syncing are built in. Factory firmware is far more limited in this area.

In exchange, you lose the ready-to-play experience, the main partition is ext4 and therefore unreadable from Windows without third-party software, and you become responsible for your own installation. It's a trade-off, not a free win.

What you need before you start

• A second microSD card of good quality, and a reliable card reader. A slow or counterfeit card causes crashes that take hours to diagnose: see our microSD card guide.
• Image-writing software. The documentation mentions Rufus, Raspberry Pi Imager, Win32 Disk Imager, or dd on the command line. The project also publishes its own tool, ROCKNIX Image Burner, for Windows only: you pick the manufacturer and the model, then “Write Image to Drive”.
• Something to unpack a .gz file.

Installing step by step

1. Identify your exact model, not the family. An RG35XX Plus, an RG35XX H and an RG35XX Pro don't take the same device tree file. The full name is printed on the box and on the back of the console.
2. Download the image from the official site. Go through your machine's page on rocknix.org, which points to the right image, or through the releases page of the ROCKNIX/distribution repository on GitHub, “Installation Package Downloads” section. The name follows the pattern ROCKNIX-PLATFORM.aarch64-DATE.img.gz. For the H700, two variants exist, DDR3 and DDR4; the documentation doesn't say how to choose, to be confirmed depending on the version — if the console doesn't boot, try the other one.
3. Check the checksum. Recent releases publish a hash alongside the images. Compare it with the one you calculate: certutil -hashfile file.img.gz SHA256 on Windows, shasum -a 256 file.img.gz on macOS and Linux. A truncated download gives a card that looks written and never boots.
4. Unpack then write the image to the second microSD card. The operation erases the card completely.
5. Allwinner H700 machines: copy the device tree. See below. Don't boot the console before you've done it.
6. Eject the card properly using your system's eject function. The documentation is explicit: skipping this step can leave the card unbootable, and you then have to start again from writing the image.
7. First boot. With the console off, insert the card and switch on. ROCKNIX runs through its installation sequence, restarts, then lands on EmulationStation. On some machines you first have to give the SD card priority in the boot order; the machine's page says so.

The device tree step on Allwinner H700

This is the quirk of every Anbernic with an H700 chip, which is most of the Linux consoles in our range. The official documentation is clear: these machines require manual steps after writing the image and before the first boot. They're done only once and aren't needed for updates.

Open the partition named ROCKNIX: it contains a device_trees folder. Find the file for your model, copy it to the root of that same partition, then rename the copy to dtb.img, in lower case.

The two indistinguishable revisions

You'll have noticed the double entries. On the RG35XX 2024, the RG35XX Plus and the RG35XX H, there are two files depending on the board revision, and the documentation says so plainly: there's no way to tell the difference without opening the machine. Same logic on the RG35XX SP with the v2-panel variant.

So the method is trial and error. Take the standard file. If the screen shows a garbled image at boot, switch off with a ten-second press on the power button, rewrite the image and start again with the other file. It isn't elegant, but it's the official procedure, and it costs a quarter of an hour.

Setting up after installation

The EmulationStation main menu opens with the Start button. The settings to deal with straight away.

• Language. French is available in the interface settings. The translation is fine for the essentials, more uneven in the advanced menus.
• Wi-Fi. Turn it on right away: it's what the scraper, online updates and network sharing depend on.
• Buttons. The built-in controls are detected at first boot. Remapping is then done from the interface, and separately in RetroArch for per-system settings. The project is currently moving the control documentation to each machine's page, and it isn't all there yet.
• Sleep and battery life. Set the sleep timer and, if the machine allows it, the processor clock: on the RG35XX Pro it runs at 1.4 GHz and can be pushed to 1.5 GHz.
• Network credentials. Samba and SSH use the user root and the password rocknix by default. Change them if the console is on a shared network.

Where to put your games

Everything starts from a roms folder, which holds one subfolder per emulated system, and where the BIOS files some emulators expect also go.

On machines with two card slots, like most Anbernic H700 models, put a card formatted as FAT32, exFAT, ext4 or btrfs in the second one: the roms folder is created there automatically at boot. On a machine with a single slot, turn on games-card auto-detection in the system settings before inserting the card.

The detail of subfolder names and the differences between firmwares is in our article on game folder structures.

The most common pitfall

It's forgetting the device tree file on the H700, or picking the wrong one. The card is written correctly, the console switches on, nothing appears. The instinct is to blame the SD card or the image, and to start over identically — for the same result.

Three checks, in order: was the file copied to the root of the ROCKNIX partition, rather than left in device_trees; is it properly renamed dtb.img in lower case, with no hidden .dtb extension added by Windows; does it really match your exact model. If all three are right, it's the board revision: try the other file.

A second pitfall, more discreet: removing the card without using your system's eject function can leave it unbootable.

Updating to a later version

The device tree step isn't repeated: it only happens at installation.

From the console. Start button, system settings, update section, then launch. You can read the changelog before confirming. Wi-Fi has to be set up.

Manually. Download the .tar file for your platform from the “Update Package Downloads” section, then copy it to /storage/.update, by SCP or through the “update” network share. Restart: the update applies by itself.

Development builds circulate on the project's Discord. They don't contain the scraper or RetroAchievements credentials: those two functions don't work there. Keep them for testing.

Going back

If you've followed the golden rule, there's nothing to do: switch the console off, put the original microSD card back, switch on. The factory firmware starts up as before, with its saves.

If you've overwritten the original card, you'll need to find the official firmware image on the manufacturer's site and write it back. It's doable, but manufacturers don't always keep them archived for long. Hence the golden rule.

In both cases, retrieve your saves before switching: they aren't shared between the two systems.

Frequently asked questions

Going further

The device tree step is only a procedural detail: it shouldn't weigh on your choice of machine. Look first at screen size, battery life and the systems you're aiming for. Our ROCKNIX-compatible machines are gathered in the Linux retro consoles collection, and each product page states the exact chip, and therefore the image to download.