FS-UAE Configuration Files

Most FS-UAE settings are controlled via configuration files. The available options are listed in the configuration options page. Also see paths and directories for more relevant information.

You can use FS-UAE Launcher, a user-friendly graphical interface instead of writing configuration files manually.

Default Configuration File

The following configuration fileΒ  will be automatically loaded unless the program is started with another configuration file (for instance by “opening” a configuration file in FS-UAE):


On Windows, make sure it isn’t really called Default.fs-uae.txt. It is easy to be fooled since Windows Explorer hides the file extension by default.

Specifying Paths in Configuration Files

Paths in configuration files can be specified as either:

  • Relative paths
  • Absolute paths
  • Paths beginning with special variables

On Windows, you must either use forward slashes in paths in configuration files, or you must use double backslashes. Example: C:/Amiga/Files and C:\\Amiga\\Files are both correct, but C:\Amiga\Files is not!

Relative paths will be looked up relative to either the current directory, or most often relative to a relevant default directory. For example, relative floppy image paths will be looked up relative to the Floppies directory.

Absolute paths are paths beginning with a drive letter (Windows), or a slash (Linux, Mac OS X, FreeBSD).

To avoid having to use absolute paths, and to make configuration files more portable, you can prefix paths with some special variables (Note: these are not environment variables, though $HOME looks like one):

  • $CONFIG – The directory containing the loaded configuration file.
  • $EXE – The directory containing the currently running FS-UAE executable.
  • $APP – On Mac OS X, the directory containing the currently running FS-UAE.app, on other platforms, it is he same as $EXE.
  • $HOME – The user’s home directory.
  • $DOCUMENTS – The user’s documents directory.
  • $BASE – The FS-UAE base directory, usually Documents/FS-UAE.

Custom Configuration File

To load a custom configuration instead of the default, just give the path to the configuration file as a program argument, Example for Windows:

fs-uae.exe D:/example/CustomConfig.fs-uae

For other platforms, something like:

fs-uae /example/CustomConfig.fs-uae

This also means that you can (in most desktop environments):

  • Associate .fs-uae files with the FS-UAE application, so FS-UAE starts with the configuration if you open the .fs-uae file.
  • Drag and drop .fs-uae configuration files to the FS-UAE application icon.

FS-UAE Launcher and Configuration Files

FS-UAE Launcher will list all configuration files found in Documents/FS-UAE/Configurations in a convenient list view.

Relative Configuration File

If you are creating a portable FS-UAE setup, you will want FS-UAE to automatically find the correct configuration file even if the program is moved around. Before looking for Default.fs-uae, FS-UAE will look for the following file in the directory containing the executable:


So for instance, if you had the windows version of FS-UAE installed in E:\Software\FS-UAE, and the executable is E:\Software\FS-UAE\FS-UAE.exe, it will then try to first find:


Inside that configuration file, you can also prefix paths with:

  • $CONFIG/ (the directory containing the configuration file), or
  • $EXE/ (the directory contaning the executable)

In this specific case, these should be the same. For example, you could use the base_dir option to have FS-UAE create its default directories in this same directory:

base_dir = $CONFIG/

And FS-UAE will then use/create the following directories (and more):

  • E:\Software\FS-UAE\Floppies
  • E:\Software\FS-UAE\Kickstarts

Hidden Default Configuration File

FS-UAE automatically creates a number of sub-folders in Documents/FS-UAE on startup. If you wish to avoid this behavior, you can use the base_dir option to specify an alternative directory. But obviously, it does not make any sense to specify this in Documents/FS-UAE/Configurations/Default.fs-uae.

If the following configuration file is found, it will be used as the default configuration file instead of Default.fs-uae:


And by specifying the base_dir option there, you can have FS-UAE create the default directories somewhere else.

Host Options File

The file Host.fs-uae is always read in addition to Default.fs-uae (or the specific configuration file used when launching FS-UAE). Common settings such as fullscreen and scanlines can be set here. Options in Host.fs-uae will be applied first, so you can override the defaults set here in the primary configuration file.

When using FS-UAE Launcher, the Host.fs-uae file is ignored.

19 thoughts on “FS-UAE Configuration Files

  1. [ 47 year old S/W dev ] I was looking for example configuration files so I can work out how to use options.
    I am setting up a GOTEK on an A600 and using an Ubi [16.04] machine and FS-UAE to build my collection up.
    I have no idea what to do with the option:-

    Is it like a ‘flag’, put it in the config file plain, or, do I need

    writable_floppy_images = true

    …I have no idea.
    I hope it’s not my dyslexia getting in the way again!

  2. When I select a game game rom with 2 files and launch the emulator. Gets to a point where asks for DISK2 and doesnt continue.

    I have the standard A500 config that comes whe first downloaded the emulator.


    • The game probably only supports one disk drive. Press the F12 key to enter the menu and then change the disk inserted into the first disk drive.

  3. How can I change the Config Folder from “C:\Users\\OneDrive\Dokumente\FS-UAE” to “C:\Users\\Dokumente\FS-UAE” on Windows 10 because I don’t like Applications who filling up my cloud space! =(

    • Hi, you can check the section “Base Directory” on https://fs-uae.net/paths. There isn’t any GUI control for that yet, so a manual config file creation is needed for that. However, you can alternatively just use the portable version (instead of the installer) and put that anywhere you like!

  4. I’m on OS X and having an issue setting base-dir if spaces are in the path.

    If I start from the command line like this:

    ./FS-UAE\ Launcher.app/Contents/MacOS/fs-uae-launcher –base-dir=/Volumes/Storage\ HD/Emulation/Commodore\ Amiga/FS-UAE\ Setups/

    Works fine. If I copy /Volumes/Storage\ HD/Emulation/Commodore\ Amiga/FS-UAE\ Setups into ~/Library/Preferences/fs-uae/base-dir quickly starts and closes.

    If there a way to correctly escape the spaces using the base-dir file?

    (Tried with 2.7.16dev and 2.8.0, both x86_64)

  5. Hi, the $BASE absolute path is always automatically set for the portable version? For example if I decide to move the FS-UAE folder, will the $BASE reflects the new home? Thanks

      • Thanks very much Frode. For all !!

        PS.: by the way, sorry for the off topic, bubba’n’stix no longer seems downloadable…

        • Yes, back2roots is unfortunately down (and has been for over a year). I had removed the back2roots downloads, but this one remained by mistake -> Fixed πŸ™‚

          • The WHDLoad install has never been there. You can install it yourself by getting the installer from whdload.de, to be used with the 3 ADF files, but there isn’t any advantage over the disk version as I’m aware of, other than a bit shorter loading time.

  6. Since the convention on OS X is to store preference data in ~/Library/Preferences/ it would be much simpler to store everything there by default and offer a GUI option to save settings/configurations/preferences somewhere else. Something which is very unlikely to ever be used on OS X since users tend to just use the application defaults anyway.

    Requiring people to manually create a file in a system folder in order to tell a program where to store its own configuration data at the proper place (in that same folder) is quite inexplicable to non developer users…

    • Hi, FS-UAE stores data in Documents/FS-UAE for historical reasons. Before FS-UAE Launcher, the used had to create configuration files manually. If FS-UAE Launcher / FS-UAE had been launched today, it would indeed probably store preferences in ~/Library/Preferences/, since with the FS-UAE Launcher GUI, the user does not have to interact directly with the files. It is also quite possible that I’ll change the default behaviour in future versions.

      But I do not expect people to “manually create a file in a system folder in order to tell a program where to store its own configuration data”. I expect (most) people to just use the defaults (as you said, users tend to just use the application defaults anyway). The option is just there for the few people who really want to change it πŸ™‚

      And I will also probably create a GUI control to select/change data directory. It’s just more work, and not on the top of the priority list πŸ™‚

  7. Hi Frode,

    After many hours of pure enjoyment with FS-UAE, I discovered a little bug in fs-uae-launcher:

    The path is not expanded for screenshots_output_dir. In my config, I have:
    screenshots_output_dir = Screenshots
    ==> fs-uae tries to write in ./Screenshots instead of $BASE/Screenshots

    I tried the following:
    screenshots_output_dir = $BASE/Screenshots
    ==> fs-uae says : “Directory does not exist: $BASE/Screenshots”.

    a little strace says:
    access(“$BASE/Screenshots”, F_OK) = -1 ENOENT (No such file or directory)

    So I conclude that screenshots_output_dir is treated as is, and not expanded.

    Happy debugging and thank you for all your work.


    • Thank you for the bug report, this is fixed for the upcoming 2.5.27dev version πŸ™‚

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.