How to Use RomM: The Beginner's Guide (First Deploy, the Folder-Structure Rule, First Scan, and the Own-Your-ROMs Lesson)

CodexFuse Team · 2026-11-01T11:28:36.000Z · 14 min read min read

A complete beginner's guide to RomM — the self-hosted ROM manager — covering the Docker deploy, the folder-structure rule, the first scan, metadata providers, users, collections, and in-browser play.

Learning how to use RomM is the fastest way to turn a messy pile of game files into one beautiful library you can browse and play from any device in the house. RomM is a self-hosted ROM manager: you run it on your own machine with Docker, point it at your game files, and it scans them, pulls in cover art and descriptions, and hands you a modern web library with in-browser play. This RomM tutorial walks the whole beginner arc in one place — the Docker deploy, the folder-structure decision you must make before you start, the first scan, metadata providers, users, and collections. If you have never touched Docker, read our Docker beginner guide first; everything below assumes you can run one compose file.

What Is RomM? (And the One Name You Must Not Confuse It With)

RomM is a self-hosted web application that organizes a ROM collection: it scans your game files, matches them against game databases, and presents them as a searchable library with box art, descriptions, screenshots, and achievements. As a self hosted ROM manager, RomM keeps every byte of the collection on hardware you control. The name collision to clear up immediately is Steam ROM Manager — a completely different product that injects games into your Steam library as non-Steam shortcuts. RomM is rommapp/romm, the open-source project on GitHub (14,186 stars, AGPL-3.0 license, as of November 2026): a server you host, a library you browse in a browser.

One rule is load-bearing before anything else: RomM manages the ROMs you already have legal rights to — rips of cartridges you own, homebrew, and public-domain releases. It is a library manager, not a source of games, and it ships with no games inside. Keep that framing and every step below stays on solid ground.

RomM vs EmuDeck vs RetroArch: Who Actually Does What

Beginners constantly mix these tools up, so here is the division of labor in one sentence: RomM organizes, RetroArch plays, Batocera is a whole operating system. The ZimaOS documentation puts it cleanly — RomM scans your files, pulls box art and metadata, and gives you a shareable library to browse, and it is not the emulator itself. RetroArch is the emulation frontend that actually runs the games across dozens of systems, and Batocera turns an entire device into a console by replacing its operating system. A common setup is keeping the collection tidy in RomM on a home server and playing on a RetroArch or Batocera device.

EmuDeck is the odd one out: it is an installation and configuration script for Steam Deck and desktop PCs, not a library manager. It installs emulators, configures controller mappings and universal hotkeys, and uses Steam ROM Manager to add games to your Steam library. Because EmuDeck's default folder layout is compatible with RomM's preferred structure, you can point RomM at an existing EmuDeck library instead of reorganizing anything. If you want the media-server parallel, our Seer beginner guide covers the request lane — Seer handles requests for a Plex or Jellyfin server, while RomM is the library lane for retro games.

How Do You Use RomM? The 10-Step Short Version

If you want the whole arc before the detail, this is how to use RomM from zero to playing:

1. Get Docker running on the machine that will host RomM.
2. Arrange your ROMs in Structure A: one roms folder with a subfolder per platform, plus an optional bios folder.
3. Copy the official docker-compose.example.yml, fill in the database passwords, your library paths, and an auth secret from openssl rand -hex 32.
4. Add at least one metadata provider — Hasheous alone works with zero API keys.
5. Save it as docker-compose.yml and run docker compose up -d.
6. Open http://localhost:80 and finish the setup wizard, which creates your admin user.
7. Press Scan in the sidebar, pick your metadata providers, and let it run.
8. Browse the library, fix any mismatches by hand, and curate collections.
9. Create extra users or invite links for family and friends.
10. Open RomM from any device on your network and press play in the browser.

Step 1: Get Docker Running on Your Host

The RomM Docker setup is the officially documented path, so a working Docker install is the one hard prerequisite — the official quick-start guide lists it before anything else. Any Linux host works; a home server, a mini PC, or a virtual machine all do the job, and Docker Desktop on Windows can host it too if you mount your ROM folders into the container. For the full Docker-first walkthrough, see our Docker setup walkthrough.

Decide where the server will live before you deploy: an always-on machine on your home network is the classic choice, because RomM is a server you leave running. A VPS works too when you want access away from home — that decision is covered in the hosting section below.

Step 2: Decide Your Folder Structure Before You Deploy Anything

This is the one decision you cannot cheaply redo later, so make it before the first scan: RomM requires one of two folder layouts, and it auto-detects Structure A first, falling back to Structure B. Get the RomM folder structure right and everything downstream — the Docker mount, the scan, the library itself — just works. Structure A is a single roms root with one folder per platform inside it, plus a separate bios root with per-platform BIOS folders. Structure B nests a roms and bios folder inside each platform folder instead.

The Docker mount rule follows from the choice: with Structure A you mount the parent of the roms folder as /romm/library; with Structure B you mount the parent of the platform folders. The BIOS folder is optional and only matters for platforms whose emulators need BIOS files. Two conveniences soften the decision: if you upload through the web UI, RomM creates Structure A for you automatically, and platform folders use each system's slug (snes, ps, gba), remappable in config.yml if your folders are named differently.

File naming matters more than most beginners expect. RomM parses region and revision tags from filenames — (USA), [HACK], and rev-1 style tags all become searchable metadata. For multi-file games kept as folders, special subfolder names like dlc, hack, manual, mod, patch, update, demo, translation, and prototype show up as tags on the game in the web UI.

Step 3: Write the Compose File (Current: RomM 5.4.1)

The current release is RomM 5.4.1, published October 22, 2026, and the supported deploy path is the official compose file — download docker-compose.example.yml from the GitHub repo and edit it rather than writing one from scratch. The file defines two services: romm from the rommapp/romm:latest image (published on host port 80, container port 8080) and romm-db from mariadb:latest. Three values need your input: the MariaDB passwords (MARIADB_ROOT_PASSWORD and MARIADB_PASSWORD, mirrored in the app's DB_PASSWD), an auth secret in ROMM_AUTH_SECRET_KEY generated with openssl rand -hex 32, and your three host paths for the library, assets, and config volumes.

Keep the database names as the example sets them unless you have a reason to change them: MARIADB_DATABASE=romm, MARIADB_USER=romm-user, matched by the app's DB_NAME and DB_USER. The library volume must be the parent folder your chosen structure expects — mount the wrong level and the scanner finds nothing, which is the single most common first-deploy failure. Save the finished file as docker-compose.yml and bring it up with docker compose up -d, then confirm both containers are healthy with docker ps -f name=romm.

Step 4: Open RomM and Finish the Setup Wizard

The first time you open http://localhost:80 (or your server's IP with port 80), RomM shows a setup wizard instead of a login page. There are no default credentials to look up: the wizard asks you to create the admin username and password, confirms your metadata sources, and only then lets you in. That first account is always an Admin with full access, including user management and background tasks.

Treat that admin account like the root key it is — give it a strong unique password, and do your daily browsing as a regular user if you add one later. The wizard runs exactly once; after the first user exists, the login page takes over permanently.

Step 5: Run Your First Scan — and Give It Time

Scanning is the heart of a RomM setup: RomM walks your library, hashes the files, queries your metadata providers, and writes everything into its database. Click Scan in the sidebar, select which providers to query, and start. You can click into games and see their metadata while the scan is still running — there is no need to wait for the whole job to finish before exploring.

Now the patience lesson, said plainly once: a big library takes a while to scan, and that is normal. Hash-based matching (Hasheous) is dramatically faster than name-based matching against the big databases, so your provider choice directly sets the wait. RomM offers six scan modes — New Platforms, Quick, Unmatched, Update, Hashes, and Complete — and scans can also run on a schedule or trigger automatically when files change via the filesystem watcher (WATCHER_ENABLED=true). For the first run, a Complete scan with your chosen providers is the right call; later, Quick or Unmatched scans handle new additions in a fraction of the time.

Step 6: Choose Your RomM Metadata Providers

Metadata is what turns filenames into a library — titles, descriptions, cover art, screenshots, and achievements all come from external providers you configure with environment variables. You do not need all of them, and the official docs rank combinations by need. The recommended setup for most users is Hasheous plus IGDB plus SteamGridDB plus RetroAchievements: hash-based matching with IGDB data proxied through Hasheous, extra metadata from IGDB itself, high-quality alternate covers from SteamGridDB, and achievement progress from RetroAchievements.

The zero-friction path is Hasheous alone — free, open-source, hash-based, no API keys, and the fastest scans. The no-Twitch path is ScreenScraper plus RetroAchievements, a free French database covering more than 125 systems. IGDB is the heavyweight (200+ systems) but demands a Twitch account with a verified phone number, a uniquely-named developer app of Confidential type, and its client ID and secret in your compose file. Two gotchas to know: MobyGames requires a paid API key, so the docs steer beginners to ScreenScraper instead; and SteamGridDB is not a scan source at all — it feeds the "search cover" button when you edit a game by hand. RetroAchievements needs each user to set their own username in their profile after an Unmatched scan before the Achievements tab appears.

Step 7: Press Play Right in the Browser

Here is the payoff the older tutorials bury: the default RomM image bundles EmulatorJS, an in-browser emulator covering NES, SNES, N64, PlayStation, Saturn, and more than twenty additional cores, plus Ruffle for Flash and Shockwave games. Open any game in your library and press play — no emulator to install, no ROM to copy to the device you are holding. On phones you get touch controls; controllers work in both the RomM interface and the games themselves.

Because everything runs against the one server, your saves live there too: start a game on your phone, save, and continue on your PC exactly where you left off. RomM records each play session automatically, which powers the Continue Playing ribbon and per-game playtime totals. Multiplayer works through EmulatorJS netplay for two or more players across the internet, though reliable NAT traversal needs STUN/TURN servers configured in config.yml.

Step 8: Add RomM Users for Family and Friends

A RomM server really earns its keep as a shared household library, and the user system is built for exactly that. Beyond your admin account, there are two roles: Admins bypass all permission checks, while regular Users get whatever their permission group grants — a grant matrix over read, write, and delete actions per area — plus any per-user overrides you set. One group is marked the server-wide default and applies automatically to every new account.

You can create users three ways: directly on the admin page (usable immediately), with a single-use invite link that lets the recipient pick their own credentials (links expire after 600 seconds by default), or automatically on first login if you wire up OIDC single sign-on. The thoughtful touches are per-user: you can hide specific platforms or ROMs from a person or a whole group, each user syncs their own RetroAchievements username, and companion apps like Argosy on Android or Grout on handhelds authenticate with per-user API tokens. If you ever want a public demo or a wall display, kiosk mode makes every read endpoint anonymously browsable while blocking all writes.

Step 9: Curate With Collections

Once the scan is done, platforms are just the starting grid — collections are how you make the library yours. A collection is a named grouping of ROMs: every Mario game, every co-op title, every game you actually intend to finish this year. Smart collections go further and populate themselves from rules, while virtual collections are auto-generated read-only groupings by genre, developer, year, or tag. Curate a handful of collections early and the Home page stops being a wall of platforms and starts being your shelf.

Where Should Your RomM Server Live?

A RomM self hosted setup belongs on a machine that is on whenever you might want to play: a home server, a mini PC, or a NAS that runs Docker keeps the library on your LAN with zero hosting cost. If you want the library reachable away from home, a VPS is the natural next step — read what VPS hosting actually is before renting one, since an always-on server has a monthly cost a home PC does not. Either way, put HTTPS in front of it before sharing with anyone outside the house: RomM's install-as-an-app PWA feature requires HTTPS, and a reverse proxy is the standard way to get it — our Caddy beginner guide covers the simplest path.

Beginner Mistakes That Break a RomM Library

Almost every broken first deploy traces back to one of these. The table is short enough to check before you run the scanner.

Sources

Every fact in this guide was verified against a page fetched on November 1, 2026: the RomM quick-start guide, folder-structure guide, metadata-provider guide, users-and-roles guide, and glossary on docs.romm.app; the rommapp/romm repository and release data via the GitHub API; the ZimaOS RomM documentation on zimaspace.com; XDA Developers' RomM setup tutorial (October 2024) and retro-game streaming story (September 2026); and the ROM-manager comparison on umatechnology.org.

Frequently Asked Questions

Is RomM the same as Steam ROM Manager?

No, and this is the most common confusion in search results. RomM (rommapp/romm) is a self-hosted web ROM manager — a server that organizes your game library and plays games in the browser. Steam ROM Manager is a different product that adds games to your Steam library as non-Steam shortcuts, typically as part of an EmuDeck setup. They solve different problems and share nothing but three letters.

Do I need API keys to use RomM?

No. RomM works without any metadata API for basic use, and enabling the free Hasheous provider takes one environment variable with no keys at all — the official docs call this the Quick Starter combo and note its scans are incredibly fast. API keys (IGDB, ScreenScraper, SteamGridDB, RetroAchievements) buy you richer metadata, more systems, and achievements, and the docs recommend setting up IGDB keys to avoid edge-case setup problems.

How long does the first RomM scan take?

It depends on your library size and your providers — a big collection takes a while, and that is normal. Hash-based matching through Hasheous is the fastest option; name-based matching against the large databases is slower but more thorough. You can browse games and their metadata while the scan is still running, and later additions only need a Quick or Unmatched scan.

Can I use RomM without Docker?

Docker is the officially documented path — the quick-start guide assumes it — and it is what this guide covers. Community options exist, including a Proxmox helper script and one-click installs on platforms like ZimaOS and Unraid, but the compose file is the reference deployment the documentation is written against.

Can other people use my RomM server?

Yes — multi-user support is a core feature. Create accounts on the admin page, send single-use invite links, or enable OIDC single sign-on; permission groups control what each person can see and do, and you can hide specific platforms or games per user. Everyone gets their own saves, playtime, achievements, and API tokens for companion apps, while the library itself stays centralized.