Amiberry directories

Amiberry Directories

Overview

Amiberry used to behave mostly like a portable app, expecting everything under the directory it was started from. Modern builds still support that mode, but the default directory layout now follows the host platform more closely.

This page documents the directory logic that is actually implemented in the codebase.

Quick reference

Environment-variable support is platform-specific:

Platform	Supported overrides
Linux	AMIBERRY_DATA_DIR, AMIBERRY_HOME_DIR, AMIBERRY_CONFIG_DIR, AMIBERRY_PLUGINS_DIR
macOS	AMIBERRY_HOME_DIR
Windows	AMIBERRY_HOME_DIR

With the exception of Linux AMIBERRY_DATA_DIR, these non-empty overrides are treated as explicit targets and created later if needed. AMIBERRY_DATA_DIR still needs to point to an existing bundled data directory.

Amiberry also supports an optional base_content_path entry inside amiberry.conf. That setting is loaded after amiberry.conf is found and lets the Paths panel derive the managed content/config directories from a single root without relying on environment variables.

If you want to keep the portable mode behavior

If you prefer the older portable behavior, create an empty file named amiberry.portable next to the executable. When Amiberry sees that marker on startup, it switches to portable mode and resolves the bootstrap settings directory plus all managed writable paths relative to the executable directory, not the current working directory.

Official Windows portable ZIP releases already include this marker, so no manual setup is required after extracting them. The executable directory must also be writable if you want to toggle portable mode from the GUI or keep portable settings and content there.

Portable mode is currently supported on Windows and Linux-style desktop builds. macOS and Android ignore the marker and continue using their normal per-user locations.

amiberry.conf

The bootstrap location of amiberry.conf and amiberry.ini depends on the platform:

• Linux: $XDG_CONFIG_HOME/amiberry/amiberry.conf, which defaults to ~/.config/amiberry/amiberry.conf. In Flatpak builds this typically becomes ~/.var/app/com.blitterstudio.amiberry/config/amiberry/amiberry.conf.
• macOS: ~/Library/Application Support/Amiberry/amiberry.conf
• Windows: %LOCALAPPDATA%\\Amiberry\\amiberry.conf
• Android: the app-private settings directory returned by SDL_GetPrefPath("BlitterStudio", "Amiberry")
• Portable mode: <portable-root>/Settings/amiberry.conf

If the file exists, Amiberry loads the paths stored inside it instead of using only the platform defaults.

The optional base_content_path entry inside amiberry.conf can then redirect the managed content/config directories from one root, but it does not relocate amiberry.conf or amiberry.ini themselves.

Directory mapping

This is the startup logic Amiberry uses for its directory roots.

DATA

The DATA directory is where the bundled data tree lives.

• Linux: AMIBERRY_DATA_DIR is honored if it points to an existing directory. Otherwise Amiberry checks the install prefix (for example /usr/share/amiberry/data) and then an executable-relative data directory for local builds or unpacked trees.
• macOS: the DATA directory is inside the application bundle.
• Windows: the DATA directory is expected relative to the executable.

HOME

The HOME directory is the root used for user content such as floppies, hard drives, ROMs, savestates, screenshots, and the logfile.

macOS

• If AMIBERRY_HOME_DIR is set and non-empty, that becomes HOME.
• Otherwise HOME defaults to ~/Documents/Amiberry.

Linux

• If AMIBERRY_HOME_DIR is set and non-empty, that becomes HOME.
• Otherwise HOME defaults to $HOME/Amiberry.
• If that still cannot be resolved, Amiberry falls back to executable-directory behavior.

Windows

• If AMIBERRY_HOME_DIR is set and non-empty, that becomes HOME.
• Otherwise HOME defaults to %USERPROFILE%\\Amiberry.

CONFIG

The CONFIG directory is where Amiberry stores .uae configuration files.

macOS

• $AMIBERRY_HOME_DIR/Configurations if AMIBERRY_HOME_DIR is set
• Otherwise ~/Documents/Amiberry/Configurations

Linux

• AMIBERRY_CONFIG_DIR if it is set
• Otherwise $HOME/Amiberry/conf
• Fallback: executable directory + /conf

Windows

• AMIBERRY_HOME_DIR\\Configurations if AMIBERRY_HOME_DIR is set
• Otherwise %USERPROFILE%\\Amiberry\\Configurations
• Portable mode: <portable-root>\\conf

PLUGINS

The PLUGINS directory is where optional shared-library plugins such as capsimage or FloppyBridge live.

• Linux: AMIBERRY_PLUGINS_DIR is honored if it is set and non-empty. Otherwise Amiberry tries the install libdir, then $HOME/Amiberry/plugins, then the executable directory + /plugins.
• macOS: plugins are bundled inside the application at Resources/plugins/.
• Windows: plugins are expected under the executable directory's plugins folder.

Base content folder (base_content_path)

The Paths panel can store an optional base_content_path inside amiberry.conf.

• This is intended for the "move my Amiberry content tree somewhere else" use case, especially on macOS where double-click app launches do not naturally inherit shell environment variables.
• When set, Amiberry derives the standard managed content/config directories from that root using platform-specific folder names.
• The derived layout uses a separate visual-assets subtree, so Themes, Shaders, and Bezels no longer live inside the machine-configuration directory.
• In the GUI, the field is staged until you click Apply.
• If the chosen root is missing managed folders, Amiberry shows which ones are missing and lets you decide whether to create them before applying the change.
• Editing an individual path afterwards turns that entry into an explicit override.
• Clearing the setting removes the bulk root and restores only the entries that were still following it to the normal platform defaults, while preserving explicit per-path overrides.
• This does not move the bootstrap location of amiberry.conf or amiberry.ini; it only changes the managed directories recorded inside amiberry.conf.

Derived folder names

macOS / Windows

• Configurations
• Visuals/Themes
• Visuals/Shaders
• Visuals/Bezels
• Controllers
• Whdboot
• Lha
• Floppies
• Harddrives
• CDROMs
• Roms
• RP9
• Savestates
• Screenshots
• Ripper
• Inputrecordings
• Nvram
• Videos

Linux

• conf
• visuals/themes
• visuals/shaders
• visuals/bezels
• controllers
• whdboot
• lha
• floppies
• harddrives
• cdroms
• roms
• rp9
• savestates
• screenshots
• ripper
• inputrecordings
• nvram
• videos

Linux default split layout

When base_content_path is not set, Linux keeps a split default layout:

Directories in XDG data

These are created under $XDG_DATA_HOME/amiberry (or ~/.local/share/amiberry if that variable is unset):

• controllers
• whdboot
• ripper
• inputrecordings
• nvram
• videos

Directories in HOME

These are created under the configured HOME directory:

• visuals
• lha
• floppies
• harddrives
• cdroms
• roms
• rp9
• savestates
• screenshots
• amiberry.log

macOS default layout

On macOS, the managed content directories are created under ~/Documents/Amiberry by default, using the title-cased folder names from the base_content_path list above (Roms, Floppies, Harddrives, Visuals, and so on). If AMIBERRY_HOME_DIR is set, the same naming is used under that directory instead.

The bootstrap settings files (amiberry.conf and amiberry.ini) are stored separately under ~/Library/Application Support/Amiberry.

If Amiberry imports bootstrap settings or visual assets from an older layout, it keeps the old files in place for safety first. A later launch can then offer to move those leftover legacy files and folders to Trash after the new layout has already been used successfully.

This keeps Amiberry aligned with the host platform while still allowing an explicit executable-relative portable mode, environment overrides, and a single-root Paths-panel override when needed.