Download Latest Version 5.4.1 source code.zip (36.7 MB)
Home / 5.3.0
Name Modified Size InfoDownloads / Week
Parent folder
5.3.0 source code.tar.gz 2026-09-21 33.5 MB
0
5.3.0 source code.zip 2026-09-21 35.2 MB
0
README.md 2026-09-21 39.3 kB
0
Totals: 3 Items   68.7 MB 0

[!CAUTION]

Breaking changes

Filesystem structure must be explicitly declared

We no longer detect the filesystem layout by default, and an instance will refuses to start until explicitly declared in your config.yml. This is the equivalent of structure A:

yaml filesystem: structure: default: "roms/{platform}/{game}" firmware: "bios/{platform}"

And the equivalent of structure B:

yaml filesystem: structure: default: "{platform}/roms/{game}" firmware: "{platform}/bios"

filesystem.roms_folder and filesystem.firmware_folder have also been removed. An instance that still sets either will refuse to start and print the equivalent template.

See Custom library structure and the filesystem.structure (docs.romm.app) schema.

[!WARNING] Emulator streaming config is now one entry per container, not one per emulator. A container's host, protocol and label become the defaults for every platform it serves, and a platform block only overrides what differs. Existing streaming setups need their config.yml rewritten before the feature will come back up.

See Emulator Streaming for the new schema.

[!NOTE]

Environment variables

Emulation

variable default description
MAX_SAVES_PER_SLOT 50 Versions kept per save slot, newest first (0 disables)
STREAMING_LAUNCH_TIMEOUT 600 Seconds to wait for a streamed emulator to launch
STREAMING_STATE_HISTORY_LIMIT 50 Save states kept per ROM, emulator and user

Physical games

variable default description
UPC_LOOKUP_ENABLED true Barcode lookups when adding a physical game
UPC_LOOKUP_API_KEY - Key for the UPC lookup service
UPC_LOOKUP_URL https://api.upcitemdb.com/prod/trial/lookup UPC lookup endpoint

Recommendations

variable default description
ENABLE_SCHEDULED_BUILD_RECOMMENDATIONS true Nightly rebuild of the recommendation index
SCHEDULED_BUILD_RECOMMENDATIONS_CRON 30 5 * * * When that rebuild runs

Browser players

variable default description
DISABLE_JSDOS false Disable the js-dos player for everyone
DISABLE_PICO8 false Disable the PICO-8 player for everyone

Metadata providers

variable default description
DEMOZOO_API_ENABLED false Enable the Demozoo metadata provider
POUET_API_ENABLED false Enable the Pouët metadata provider
CSDB_API_ENABLED false Enable the CSDb metadata provider
STEAM_API_ENABLED false Enable the Steam storefront metadata provider
HASHEOUS_API_URL https://hasheous.org/api/v1 Use a self-hosted Hasheous instance

General

variable default description
SCAN_WORKERS 4 Parallel scan workers, was 1
WEB_SERVER_CONCURRENCY 4 API server workers, was 1
DB_POOL_RECYCLE_SECONDS 300 Recycle pooled DB connections after this many seconds

Highlights

Custom library structure

Instead of guessing between two folder structures, describe your exact library layout in config.yml. {platform} is the platform folder, the final {game} is where a game starts, and anything else in {braces} is just a folder you use to organize things. You can override the layout per platform, and give a platform a list of layouts when its games sit at more than one depth. [#3571]

ROM identity is now content-hashed, so you can move files around and keep their saves, favorites, play history and collections. And if you came from Batocera, RetroBat or ES-DE, their platform folder names are recognized out of the box, so most libraries need no mapping at all. [#4345]

:::yaml
filesystem:
  structure:
    default: "roms/{platform}/{game}"
    firmware: "bios/{platform}"
    ps3: "roms/{platform}/{category}/{game}"
    snes: "roms/{platform}/{region}/{game}"
    nes:

      - "roms/{platform}/{game}"
      - "roms/{platform}/{category}/{game}"

Docs: Custom library structure, Folder name aliases

Emulator streaming

A massive update to emulator streaming. You configure one entry per container instead of one per emulator, a platform can pool several containers and grab whichever one is free, and platforms that do both browser and streamed play now get separate Play and Stream buttons. [#4314]

Saves and save states made while streaming are pulled back into your library with history and thumbnails. Multi-disc games get a disc-swap control, and whichever disc was mounted when you saved is the one remounted when you load. PS2 and GameCube can sync a whole memory card instead of individual save files, with a memory card library to create, rename, version, share and download them. Admins get a desktop session for setting up an emulator with no game running, plus a fleet view to force-release sessions across every container.

Docs: Emulator Streaming

Physical games

Own a game on a cartridge or disc, but have no ROM for it? You can now add it anyway, by name or by scanning its barcode with your camera, and it gets matched to metadata like any other game. [#3848]

Docs: Physical Games

Screenshot 2026-09-11 at 6 00 19 PM

Walkthroughs

Walkthroughs are now documents on a game, sitting next to its manuals. Upload your own, or paste a GameFAQs URL and have it fetched directly (as plain text). It'll even remember where you left off and show a progress bar for each user. [#3816]

Docs: Walkthroughs

Screenshot 2026-09-11 at 6 03 47 PM

Title IDs read from the binary

Scans now pull a game's native Title ID straight out of its binary on PSX, PS2, PS3, PSP, PS Vita, Switch, 3DS, Wii, Wii U, GameCube, Dreamcast, Xbox and Xbox 360. It identifies games on the platforms we don't hash, so a renamed or moved file keeps its saves and collections, and it tells the system where a game writes its saves, so device sync knows what to look for. [#3925]

Docs: Title ids read from the binary

Jukebox

A soundtrack player for your whole library that follows you as a mini player anywhere in the app. Browse by album, platform, artist or genre, or just put a playlist on: Free Radio picks a randomized, album-balanced hour, and there's a Decade Mix, recently added, and your personal favorites. [#4197]

Docs: Jukebox

Screenshot 2026-09-11 at 6 05 57 PM

JS-DOS and PICO-8 in the browser

Windows 3.x and 9x games now run on js-dos and its DOSBox-X backend. Note that js-dos saves stay in your browser and are not synced back to the server. [#4061]

PICO-8 cartridges (.p8 and .p8.png) are also now playable, on FAKE-08, with keyboard + mouse, gamepad, or touch input. [#4400]

Docs: js-dos, PICO-8

Screenshot 2026-09-11 at 6 06 41 PM

Four new metadata sources

Steam is now a metadata source for the win, linux and mac platforms, no API key required! It's in the scan, in the Match ROM dialog when a PC game was missed or matched to the wrong app, and in the cover picker alongside SteamGridDB. [#4241] [#4498] [#4500]

Demozoo, Pouët and CSDb cover demoscene productions on platforms we already support. Tag a file (demozoo-108), or paste an id or a production URL into the ROM editor. [#4221]

:::yaml
scan:
  priority:
    metadata:

      - steam # PC platforms only

Docs: Metadata Providers

EmulatorJS cores and multi-disc games

A multi-disc game is handed to EmulatorJS all at once now, so you can swap discs from the emulator's own menu instead of going back and reloading. Set emulatorjs.disable_batch_bootup to boot only the disc you launched, if a core mishandles the batch. [#3988]

You can also preselect a core per platform with emulatorjs.default_cores. That sets the starting point, and anyone who has already picked a core on their device keeps their choice. [#4452]

Docs: Cores, Multi-disc games

Library-aware recommendations

Recommendations are now built from your own library, blending metadata overlap, the list pulled from IGDB, and what you actually play. You'll find them under Similar games on a game's page, and in a new Recommended for you row on the home screen. Enable it by setting ENABLE_SCHEDULED_BUILD_RECOMMENDATIONS=true in your env vars. [#4174]

Docs: Recommendations

Screenshot 2026-09-11 at 6 08 32 PM

Saves

A save syncs automatically with the server seconds after its stored in the browser. The player watches the emulator's SRAM while you play and uploads a new version as soon as one appears, so your progress is saved even if the tab is closed or the browser crashes. [#4378] [#4558]

Saves are also organized into slots, the same model used by the sync clients. Ordinary play goes to the autosave slot, which keeps a capped history; a named slot on launch keeps every version. Each version carries a screenshot from the moment it was written, and the server prunes a slot to MAX_SAVES_PER_SLOT (50 by default). [#4517] [#4540]

In-game, the Export and Import save buttons are replaced by a single Load save or state picker that restarts the game from the save you pick. [#4600] [#4615]

:::yaml
emulatorjs:
  auto_save_sync: false # opt ou & Quit

Docs: Saves & States

Sort and filter by game length

You can now sort and filter the gallery by how long a game takes, straight from the gallery rather than having to build a collection for it. It's based on the HowLongToBeat main story time, so it needs HLTB_API_ENABLED and a scan that matched the game. [#4392]

Docs: Game length

Minor changes

Fixes

Other changes

New Contributors

Full Changelog: https://github.com/rommapp/romm/compare/5.2.0...5.3.0

Source: README.md, updated 2026-09-21