ROM Properties Page shell extension

June 20, 2026 · View on GitHub

This shell extension adds a few nice features to file browsers for managing video game ROM and disc images.

License: GPL v2 AppVeyor Build status
Coverity Scan Build Status Crowdin
CodeQL CodeFactor codecov

no vibes, no bevis

v2.8

rom-properties (rpcli) showing graphics in KDE Konsole using the Kitty protocol.

Major additions in v2.8 include:

  • PlayStation TIM textures.

  • S98 audio files.

  • rpcli supports displaying icons and banners using the Sixel and/or Kitty protocols when using a terminal that supports it.

  • Improvements for Wii U firmware files, amiibo, and Lua bytecode.

  • Numerous improvements for Windows icon handling, including a fix for NT 3.x EXEs that have two 16-color icons, one of which is actually an 8-color icon.

  • Added more ARM NEON optimizations, including linear RGB decoding and Super Magic Drive decoding.

  • Windows-specific changes:

    • Fix fallback icons for files where the registered DefaultIcon has double-quotes, e.g. PowerShell .ps1 scripts.
    • GNU gettext is now built as part of rom-properties, which simplifies upgrades.

  • Lots and lots of tiny bug fixes and improvements.

Translators wanted; if you can translate rom-properties from English to another language, check out the Crowdin project. (If you would like to translate to a language not currently listed on the Crowdin project page, file an issue here on GitHub with the requested language.)

See NEWS.md for a full list of changes in v2.8.

Feedback

This is a work in progress; feedback is encouraged. To leave feedback, you can file an issue on GitHub, or visit the Gens/GS IRC channel: irc://irc.badnik.zone/GensGS

Or use the Mibbit Web IRC client: http://mibbit.com/?server=irc.badnik.zone&channel=#GensGS

Installation

Currently, the ROM Properties Page shell extension is compatible with the following platforms and file browsers:

  • KDE Frameworks 5.x and 6.x (Dolphin and Konqueror)
  • XFCE (Thunar)
  • GNOME 3.x through 42 (Nautilus)
  • GNOME 43 (Nautilus)
  • MATE Desktop (1.18+) (Caja)
  • Cinnamon Desktop (Nemo)
  • Windows 7 (and later)

The following platforms are still compatible, but may not receive as much support:

  • KDE 4.x
  • Windows XP SP3, Windows Server 2003 SP2, Windows Vista
    • Note that WinInet in older versions of Windows does not support the newer encryption algorithms used by the online database hosts. To work around this, you will need to download an older version of cURL and a certificate bundle. This is available on the Releases page.

On Windows 10 and later, you will need the MSVC 2015-2026 runtime:

On Windows Vista, Windows 7, and Windows 8.x, you will need the MSVC 2015-2022 runtime:

On Windows XP/2003 and earlier, you will need the MSVC 2015-2017 runtime:

For instructions on compiling from source, see doc/COMPILING.md.

Linux

Install the relevant .deb package, depending on what desktop environment you are using and what your CPU is.

After installing, the plugin needs to be enabled in the Dolphin file browser:

  • Close all instances of Dolphin.
  • Start Dolphin.
  • Click Control, Configure Dolphin.
  • Click the "General" section, then the "Preview" tab.
  • Check the "ROM Properties Page" item, then click OK.
  • Enable previews in a directory containing a supported file type.

If installed correctly, thumbnails should be generated for the supported file type. You can also right-click a file, select Properties, then click the "ROM Properties" tab to view more information about the ROM image.

Windows

Extract the ZIP archive to a directory, then run install.exe. The installer requires administrator access, so click "Yes" if requested. In the installer, click the "Install" button to register the ROM Properties Page DLL.

Note that this will hard-code the location of the DLL files in the registry, so you may want to place the DLLs in a common location.

To uninstall the plugin, run install.exe again, then click the "Uninstall" button.

Current Desktop Environment Feature Support

  • ✅ = supported
  • ❌ = not implemented (yet)
  • ⛔ = OS or DE does not support this feature
FeatureWindows XPWindows Vista/7/8/10/11KDEGNOMEXFCE
Properties tab✅✅✅✅✅
XAttrs tab✅✅✅✅✅
Thumbnails✅✅✅✅¹✅
"Dangerous" overlay❌❌✅✅⛔²
Metadata✅✅✅✅✅
Columns✅✅⛔³✅⛔²
Context menu⁴✅✅✅✅✅
  • 1: GNOME uses sandboxing when it runs thumbnailing software, which may prevent rom-properties from downloading images from online databases.
  • 2: ThunarX's plugin infrastructure does not have any interfaces for adding custom file attributes, such as overlays and metadata, or to display custom columns.
  • 3: KDE has a fixed set of metadata properties and does not have any mechanism to extend it, outside of updates to KFileMetaData.
  • 4: Context menu entry for supported texture formats to convert the texture to PNG.

Current File Support Level

Game Consoles

SystemProperties TabMetadataInternal ImagesExternal Images
ColecoVisionYesYesN/ANo
Commodore 64/128 .CRTYesYesN/ATitle
IntellivisionYesYesN/ANo
iQue Player ticket filesYesYesIcon, BannerNo
Microsoft Xbox (XBE)YesYesIconNo
Microsoft Xbox 360 (XEX)YesYesIconNo
Microsoft Xbox 360 (STFS)YesYesIconNo
Microsoft Xbox Game DiscsYesYesIconNo
NESYesNoN/ATitle
Super NESYesYesN/ATitle
Nintendo 64YesYesN/ANo
Nintendo GameCube DiscsYesYesBannerDisc, Covers
Nintendo GameCube BannersYesYesBannerNo
Nintendo GameCube SavesYesYesIconN/A
Nintendo Wii BannersYesYesNoNo
Nintendo Wii DiscsYesYesNoDisc, Covers
Nintendo Wii WADsYesYesYes¹Title, Covers
Nintendo Wii SavesYesYesYesN/A
Nintendo Wii SETTING.TXTYesNoNoN/A
Nintendo Wii U (Disc)YesNoNoDisc, Covers
Nintendo Wii U (Firmware)YesNoYes²N/A
Nintendo Wii U (NUS)YesYesIconDisc, Covers
Sega 8-bit (SMS, GG)YesYesN/ANo
Sega Mega DriveYesYesN/ATitle
Sega DreamcastYesYesMediaNo
Sega Dreamcast SavesYesYesIcon, BannerNo
Sega SaturnYesYesN/ANo
Sony PlayStation DiscsYesNoN/ACovers
Sony PlayStation EXEsYesNoN/AN/A
Sony PlayStation SavesYesYesIconN/A
Sony PlayStation 2 DiscsYesYesN/ACovers
  • Sega Mega Drive includes Sega CD, 32X, and Pico.
  • 1: Internal images are only present in Wii DLC WADs.
  • 2: Custom icons based on the specific firmware type.

Handhelds

SystemProperties TabMetadataInternal ImagesExternal Images
Atari LynxYesYesN/ANo
Bandai WonderSwan (Color)YesYesN/ATitle
Google AndroidYesYesIconN/A
J2MEYesYesIconN/A
Neo Geo Pocket (Color)YesYesN/ATitle
Nintendo Game Boy (Color)YesYesN/ATitle
Nintendo Virtual BoyYesYesN/ANo
Nintendo Game Boy AdvanceYesYesN/ATitle
Nintendo DS(i)YesYesIconCovers, Box
Nintendo DSi TADs*PartialNoNoNo
Nintendo 3DSYesYesIconCovers, Box
Palm OSYesYesIconN/A
Pokémon MiniYesYesN/ANo
Sony PlayStation PortableYesYesIcon, BannerNo
Tiger game.comYesYesIconNo
  • The Nintendo DSi TAD parser supports development TADs that are normally imported using DSi Nmenu. It does not currently support DSi exports from retail systems.
  • The PSP parser supports both PSP game and UMD video discs, as well as several compressed disc formats: CISOv1, CISOv2, ZISO, JISO, and DAX.
  • The Android parser currently retrieves the largest icon available.

Texture Formats

Texture FormatProperties TabMetadata
ASTC containerYesYes
Godot 3,4 .stexYesYes
Leapster Didj .texYesYes
Khronos KTXYesYes
Khronos KTX2YesYes
Microsoft DirectDraw DDSYesYes
Microsoft Xbox XPRYesYes
PowerVR 3.0.0YesYes
Quite OK Image FormatYesYes
Sega PVR/GVR/SVRYesYes
Sony PlayStation TIMYes
TrueVision TGAYesYes
Valve VTFYesYes
Valve VTF3 (PS3)YesYes
Windows icons/cursors¹YesYes
  • 1: Icon thumbnailing is disabled for ICO, CUR, and EXE files to prevent conflicts with system icon handling.
    • ...with an exception for thumbnailing 16-bit Windows executables on 64-bit Windows by hooking the PrivateExtractIcons() functions.

Texture Codecs

  • Assorted linear RGB formats, including 15-bit, 16-bit, 24-bit and 32-bit per pixel.
    • Most of these formats have SSE2 and/or SSSE3-optimized decoders.
    • RGB9_E5 is supported, though it is currently converted to ARGB32 for display purposes. The decoder is also slow. (Contributions welcome.)
  • Dreamcast: Twiddled and Vector-Quantized
  • Nintendo DS: Tiled CI8 with BGR555 palette
  • Nintendo 3DS: Tiled and twiddled RGB565
  • GameCube: Tiled RGB5A3 and CI8 with RGB5A3 palette
  • S3TC: DXT1, DXT2, DXT3, DXT4, DXT5, BC4, and BC5 codecs.
    • GameCube 2x2-tiled DXT1 is supported in GVR texture files.
  • ETCn: ETC1, ETC2 (RGB, RGBA, RGB_A1), EAC
  • BC7: Supported in multiple texture file formats.
    • The implementation is somewhat slow. (Contributions welcome.)
  • PVRTC: Supported in multiple texture file formats.
    • PVRTC-II: Partially supported. The hard transition flag and images that aren't a multiple of the tile size are not supported.
  • ASTC: Supported in multiple texture file formats.

Audio Formats

SystemProperties TabMetadataInternal ImagesExternal Scans
Atari 8-bit SAP audioYesYesN/AN/A
Atari ST SNDH audioYesYesN/AN/A
CRI ADX ADPCMYesYesN/AN/A
Commodore 64 SID MusicYesYesN/AN/A
Game Boy Sound SystemYesYesN/AN/A
Game Boy RippedYesN/AN/AN/A
Nintendo 3DS BCSTM and BCWAVYesYesN/AN/A
Nintendo Sound FormatYesYesN/AN/A
Nintendo Wii BRSTMYesYesN/AN/A
Nintendo Wii U BFSTMYesYesN/AN/A
Portable Sound FormatYesYesN/AN/A
S98 FormatYesYesN/AN/A
Super NES SPC FormatYesYesN/AN/A
Video Game MusicYesYesN/AN/A

Media Formats

SystemProperties TabMetadataInternal ImagesExternal Scans
Commodore DOS Disk ImagesYesYesGEOS*N/A
ISO-9660 Disc ImagesYesYesIconN/A
Windows Image (.wim)YesNoN/AN/A
  • Commodore DOS currently includes the 2040, 3040, 4040, 8050, 8250, 1540/1541, 1571, and 1581 disk drives, in D64, D71, D80, D82, D81, D67, G64, and G71 formats.
    • File icons for GEOS files are supported.
  • UDF disc format is not currently supported. Hybrid disc images that have both UDF and ISO-9660 data structures will be handled as ISO-9660.
  • CD-i and High Sierra disc images are handled by the ISO-9660 disc image parser.

Other

SystemProperties TabMetadataInternal ImagesExternal Scans
Executable and Linkable FormatYesNoN/AN/A
PUC Lua binariesYesNoN/AN/A
Mach-O BinariesYesNoN/AN/A
Nintendo amiiboYesNoN/AMedia
Nintendo Badge ArcadeYesYesImageN/A
Windows/DOS ExecutablesYesYesIcon¹N/A
  • 1: Icon thumbnailing is disabled for ICO, CUR, and EXE files to prevent conflicts with system icon handling.

General notes for all formats:

  • Internal image refers to artwork contained within the ROM and/or disc image. These images are typically displayed on the system's main menu prior to starting the game.
    • "N/A" here means the ROM or disc image doesn't have this feature.
    • "No" indicates that the feature is present but not currently implemented.
  • External scans refers to scans from an external database, such as GameTDB.com for GameCube and Wii.
    • "No" indicates no database is currently available for this system.
    • Anything else indicates what types of images are available.
    • For amiibo, "media" refers to the amiibo object, which may be a figurine, a card, a plush, or a wooden block.
  • Windows executables may contain multiple icon sizes. Support for Windows icons will be added once support for multiple image sizes is added.
  • Sega 8-bit only supports ROM images with a "TMR SEGA" header.

A configuration program, rp-config, is available to configure rom-properties using a graphical interface. This program allows you to configure which images will be used for thumbnails on each system, as well as other functionality.

External Media Downloads

Certain parsers support the use of external media scans through an online database, e.g. GameTDB.com. This is enabled by default, but you can customize which scans are downloaded for which systems by running the configuration program, rp-config.exe.

Downloaded images are cached to the following directory:

  • Linux: ~/.cache/rom-properties/
  • Windows XP: %LOCALAPPDATA%\rom-properties\cache
  • Windows Vista+: %USERPROFILE%\AppData\LocalLow\rom-properties\cache

The directory structure matches the source site, so e.g. a disc image of Super Smash Bros. Brawl would be downloaded to ~/.cache/rom-properties/wii/disc/US/RSBE01.png. Note that if the download fails for any reason, a 0-byte dummy file will be placed in the cache, which tells the shell extension not to attempt to download the file again. [FIXME: If the download fails due to no network connectivity, it shouldn't do this.]

If you have an offline copy of the GameTDB image database, you can copy it to the ROM Properties Page cache directory to allow the extension to use the pre-downloaded version instead of downloading images as needed.

Decryption Keys

Some newer formats, including Wii disc images, have encrypted sections. The shell extension includes decryption code for handling these images, but the keys are not included. To install the keys, create a text file called keys.conf in the rom-properties configuration directory:

  • Linux: ~/.config/rom-properties/keys.conf
  • Windows: %APPDATA%\rom-properties\keys.conf

The keys.conf file uses INI format. An example file, keys.conf.example, is included with the shell extension. This file has a list of all supported keys, with placeholders instead of the actual key data. For example, a keys.conf file with the supported keys for Wii looks like this:

[Keys]
rvl-common=[Wii common key]
rvl-korean=[Wii Korean key]

Replace the key placeholders with hexadecimal strings representing the key. In this example, both keys are AES-128, so the hexadecimal strings should be 32 characters long.

NOTE: If a key is incorrect, any properties dialog that uses the key to decrypt data will show an error message instead of the data in question.

Nintendo DS Secure Area

To encrypt or decrypt the Nintendo DS Secure Area, the Blowfish key must be named nds-blowfish.bin and placed in the same directory as keys.conf.

MD5sum: c08c5afd9c6d9530817cd2033e3864d7

Unsupported File?

If you have a file that you believe should be supported by ROM Propeties, or would like to see support added for a new type, file an issue on GitHub: https://github.com/GerbilSoft/rom-properties/issues

License

ROM Properties is licensed under the GNU General Public License v2. Some bundled components have other licenses:

  • basisu_astc: Apache License 2.0
  • googletest: BSD 3-clause
  • GCR_CMake: GPL-3
  • inih: BSD-3-clause
  • libmspack-xenia: LGPL-2.1
  • lz4: BSD 2-clause for lib/; GPLv2 for others
  • microtar: MIT
  • minizip-ng: zlib
  • PowerVR: MIT
  • rapidjson: MIT
  • PugiXML: MIT
  • unice68: GPL-3
  • uniwidth: LPGL-2.1+
  • zlib-ng: zlib
  • zstd: BSD 3-clause

GCR_CMake is only used at build time, and is only necessary for the GTK builds, so I believe it does not make the entire program GPL-3 licensed.

unice68 is linked in during compile time, but can be disabled. All builds with unice68 are therefore GPL-3+. unice68 is only used for Atari ST SNDH files, so this can be disabled if a GPL-2+ build is desired: -DENABLE_UNICE68=OFF

On Windows, the following bundled components are also used:

  • GNU gettext: GPL-3+
  • libwin32darkmode: GPL-3+

While the use of gettext can be disabled with -DENABLE_NLS=OFF, libwin32darkmode is currently always enabled, so Windows builds are always GPL-3+ at the moment.

The original version of the "Happy Wii U" icon used for Wii U firmware binaries was provided by Vixy under CC-BY licensing. The original icon was modified to fit in a 48x48 icon frame and to provide additional information, e.g. retail vs. development (green), and to show an SD card for sdboot.

The flag icons used for region/language selection are based on flag icons from Twemoji 12.0.1. Copyright 2019 Twitter, Inc and other contributors; licensed under CC-BY 4.0.

Credits

Developers

  • @GerbilSoft: Main developer.
  • @DankRank: Contributor, bug tester.
  • @CheatFreak: Bug tester, amiibo support.

Translators

  • @DankRank: Russian, Ukrainian
  • @NullMagic2: Brazilian Portuguese
  • @Amnesia1000: Spanish
  • Slippy: German
  • @CyberYoshi64: German
  • @maschell: German
  • @WebSnke: German
  • @TheOneGoofAli: Russian
  • @NotaInutilis: French
  • @xxmichibxx: German
  • @ThePBone: German
  • @ionuttbara: Romanian
  • @MaRod92: Italian
  • Motwera: Arabic
  • Chipsum: Arabic
  • spencerchris8080: Spanish
  • @NoNameWasDefined: French

Other Contributions

[This list is incomplete; if you think you should be listed here, file an issue.]

  • @Tpot-SSL: Assistance with the game.com implementation.
  • Pixy: Original "Happy Wii U" icon for Wii U firmware images. (License: CC-BY-4.0)

Websites