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):

Documents/FS-UAE/Configurations/Default.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:

Config.fs-uae

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:

E:\Software\FS-UAE\Config.fs-uae

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:

$HOME/.config/fs-uae/fs-uae.conf

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”

Mole on 2017-07-26 at 05:51 said:

[ 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:-
writable_floppy_image

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!

Reply ↓
- FrodeSolheim on 2017-07-26 at 23:50 said:
  
  Yes, you can add the following to a config file:
  
  writable_floppy_images = 1
  
  Reply ↓
Yorch on 2017-06-07 at 16:30 said:

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.

Tx.

Reply ↓
- FrodeSolheim on 2017-07-26 at 23:51 said:
  
  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.
  
  Reply ↓
Anonymous on 2016-11-11 at 23:20 said:

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! =(

Reply ↓
- FrodeSolheim on 2016-11-11 at 23:22 said:
  
  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!
  
  Reply ↓
Scott on 2016-09-16 at 04:11 said:

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)

Reply ↓
- FrodeSolheim on 2016-09-16 at 20:21 said:
  
  Hi, when putting the path in ~/Library/Preferences/fs-uae/base-dir, don’t escape it at all…
  
  Reply ↓
  - Scott on 2016-09-17 at 01:59 said:
    
    Thanks Frode. I swear I tried that, apparently I didn’t. Working great again.
    
    Reply ↓
maxfactor on 2016-03-22 at 10:03 said:

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

Reply ↓
- FrodeSolheim on 2016-03-22 at 10:09 said:
  
  Yes, when using the portable version, $BASE always points to the portable directory.
  
  Reply ↓
  - maxfactor on 2016-03-22 at 11:07 said:
    
    Thanks very much Frode. For all !!
    
    PS.: by the way, sorry for the off topic, bubba’n’stix no longer seems downloadable…
    
    Reply ↓
    - FrodeSolheim on 2016-03-22 at 13:34 said:
      
      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 🙂
      
      Reply ↓
      - maxfactor on 2016-03-22 at 14:36 said:
        
        Thanks. Can you also check for WHDLoad v1.0 about Putty Squad?
        I am really not able to find it at http://www.system3.com/promotional-download/puttysquadamiga/ (there ie just a zip with 3 adf files)
        
        Best regards
      - FrodeSolheim on 2016-03-23 at 22:14 said:
        
        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.
Laurent Giroud on 2015-01-21 at 04:35 said:

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…

Reply ↓
- FrodeSolheim on 2015-01-24 at 18:26 said:
  
  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 🙂
  
  Reply ↓
Frolp on 2014-10-02 at 10:25 said:

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.
—
Frolp

Reply ↓
- FrodeSolheim on 2015-01-24 at 15:42 said:
  
  Thank you for the bug report, this is fixed for the upcoming 2.5.27dev version 🙂
  
  Reply ↓

FS-UAE Amiga Emulator