MAME via Homebrew on Macs - Finally There (and MacPorts, actually)

Update 14 December 2025: Added a chapter for Intel Macs and for Linux (with some basic ideas how Linux should work). I also provided initial thoughts on my tests with MacPorts (instead of Homebrew), encouraging, but not fully there.

------------- original post --------------

This is a major achievement - after several unsuccessful attempts, it seems that I have finally managed to create a near-perfect MAME Homebrew setup on my Mac. Let’s explore why this effort was worth the time.

Why does this matter?

Managing your MAME install via Homebrew should address the following major issues around any MAME installation:

• MAME system and user files stay separately: With this setup

• the MAME system files, which are regularly upgraded via Homebrew, stay in the Homebrew repository of your Mac, while

• your user data, such as inis, rom files, artwork and all other content, are in a separate folder of your Mac, where MAME can find them.

• Seamless upgrades: By keeping MAME system data separate from your user data, you upgrade MAME via Homebrew without the need for any user data migration. User data upgrades are always separate from MAME system upgrades.

• No Gatekeeper woes: Running MAME via Homebrew does not hit Gatekeeper restrictions. MAME is treated like any other CLI tool installed through a trusted package manager. This is why you can launch it without the “macOS cannot verify the developer” or “move it to the bin” popups.

• Launch MAME from anywhere: Just open the Terminal and type e.g. mame 1942, and the game launches. It is no longer needed to launch MAME via Terminal from the home directory.

With only one minor deficiency that needs a workaround as explained below, it’s ready. It’s really great to keep MAME up-to-date in an admin-friendly way.

Requirements for this setup on your end

• Main instructions are for ARM64/Silicon Mac, where the necessary changes for Intel Macs are described in a separate chapter (not that difficult)
• Basic Terminal knowledge (recommendation: iTerm2 app)
• Basic Editor knowledge (recommendation: Visual Studio Code app)
• An existing Homebrew installation (for Apple Silicon)
• Understand how to access and use the hidden folder $HOME/Library/Application Support/ folder of your user account $HOME

Let's start from scratch!

Step 1 - install MAME via Homebrew

In the Terminal 

brew install mame
brew install rom-tools

(rom-tools are optional, if you also want to have MAME’s cli-tools for rom management installed)

After installation, do not start MAME, as we have plenty of further things to do.

Step 2 - create plain MAME ini files

In the Finder, create an empty directory of your choice, for this setup it will be

$HOME/Games/mame    

Technical Note: This folder is only a precautionary step for the time of the setup, after completion of this setup, you can delete this folder.

In the Terminal, change into this new directory and execute:

cd $HOME/Games/mame mame -cc

This creates the initial files mame.ini and ui.ini in this folder. Don't worry about the error about the missing plugins - it comes expected.

Technical Note: After completion of this setup, as soon as you configure your plugins within the MAME UI, the file plugin.ini is correctly created in your $HOME/Library/Application Support/mame folder. Don't create it earlier - as you might end up with the file being at the wrong place.

Step 3 - create an empty MAME Application Support folder 

It is important that you start fresh, so please check in your Application Support folder whether any prior MAME installation has created a mame directory - if so, rename it and keep it as a backup.

After this, go back to the Terminal, and from within your $HOME/Games/mame folder and start MAME for the first time:

mame

You should enter the MAME User Interface (at the time of this writing, version 0.283), exit again by Esc. By this first launch, a cfg folder has been created in your $HOME/Games/mame directory - this is not of our interest. Importantly, also a fresh folder in $HOME/Library/Application Support/mame was created. This will be the place for your User data.

Step 4 - edit mame.ini and move user data to the right place 

Now the most crucial part of the setup comes by setting up the correct mame.ini file. We will edit the mame.ini file we have created in Step 2 above.

Let's see first what we want to achieve - User Data first, this folder structure has to be set up manually (without the roms and software subfolders, only for illustration):

Technical note: These folders contain User data of various kind, as briefly explained above. In principle, they should not be affected by an actual MAME Homebrew update. Anything here is manipulated by you, but not Homebrew. 

Please move all of your user data into the appropriate directories. The root directory of MAME should remain empty for now.

In contrast, the system data provided by Homebrew covers the following directories. These have already been set up automatically by the Homebrew installation of MAME:

Technical note: There should be no need for you to manipulate these folders, so let Homebrew deal with them. As an exception please already take note of the artwork/bgfx folder, which we need to cover in the last step of this setup.

As soon you have set up the User Data Structure, the mame.ini file needs to be changed as follows:

Starting from line 7:

# # CORE SEARCH PATH OPTIONS # homepath "$HOME/Library/Application Support/mame/" rompath "$HOME/Library/Application Support/mame/roms" hashpath /opt/homebrew/share/mame/hash samplepath "$HOME/Library/Application Support/mame/samples" artpath "$HOME/Library/Application Support/mame/artwork" ctrlrpath "$HOME/Library/Application Support/mame/ctrlr" inipath "$HOME/Library/Application Support/mame;$HOME/.mame;.;ini" fontpath "$HOME/Library/Application Support/mame/fonts" cheatpath "$HOME/Library/Application Support/mame/cheat" crosshairpath "$HOME/Library/Application Support/mame/crosshair" pluginspath /opt/homebrew/share/mame/plugins languagepath /opt/homebrew/share/mame/language swpath "$HOME/Library/Application Support/mame/software" # # CORE OUTPUT DIRECTORY OPTIONS # cfg_directory "$HOME/Library/Application Support/mame/cfg" nvram_directory "$HOME/Library/Application Support/mame/nvram" input_directory "$HOME/Library/Application Support/mame/inp" state_directory "$HOME/Library/Application Support/mame/sta" snapshot_directory "$HOME/Library/Application Support/mame/snap" diff_directory "$HOME/Library/Application Support/mame/diff" comment_directory "$HOME/Library/Application Support/mame/comments" share_directory /opt/homebrew/share/mame/share

Technical notes: These changes to the folder paths reflect the structure outlined above. It is important that virtually all output directories are placed in your User directory, since MAME will write data into them. This arrangement also ensures that MAME does not write data into the directory from which you launch the program. For this reason, you can eventually delete the $HOME/Games/mame folder, as it is no longer needed.

Change of line 256 (assuming that you want BGFX shaders):

video bgfx

And starting from line 253:

# # OSD VIDEO OPTIONS # video bgfx numscreens 1 window 0 maximize 1 waitvsync 0 syncrefresh 0 monitorprovider auto

Starting from line 350:

# # BGFX POST-PROCESSING OPTIONS # bgfx_path /opt/homebrew/share/mame/bgfx bgfx_backend metal bgfx_screen_chains crt-geom bgfx_shadow_mask slot-mask.png bgfx_lut lut-default.png bgfx_avi_name auto

Technical note: Quite importantly, bgfx uses the Homebrew path.

Then move mame.ini: The modified mame.ini file is ready for being moved into the $HOME/Application Support/mame folder.

Step 5 - workaround for BGFX Artwork

Now the only workaround that needs to be applied: For some reason, the folder /opt/share/mame/artwork/bgfx must be copied into your user artwork directory. I tested several mame.ini settings, but multiple artwork folders proved unreliable and caused errors with the BGFX shaders. Therefore, copy your BGFX folder by executing the following Terminal command:

cp -R /opt/homebrew/share/mame/artwork/bgfx "$HOME/Library/Application Support/mame/artwork/"

These are the only system files that require manual upgrades if the BGFX artwork is changed in future MAME versions. This appears to be a negligible issue - according to GitHub, the BGFX artwork folder has seen only a minor change to a single file in the past two years. However, if in doubt, simply replace the BGFX artwork folder by running the above Terminal command after upgrading MAME.

Step 6 - test, backup and tweak further

MAME should be ready for testing. From any directory, fire up one of your favorite games in the terminal, e.g. mame 1942, and all should be up and running - including BGFX shaders.

If everything runs as it should be: This is a good moment to backup your mame.ini for further use. Treat it carefully, you used a lot of time on it.

You then can apply any further tweaks to mame.ini, such as drom the following postings:

• the throttle/waitvsync hack 
• joystick configurations
• low latency
• audio effects

If all is fine, just enjoy your MAME installation and further upgrades from within Homebrew! As always, feedback would be much appreciated.

Necessary Changes for Intel Macs

Setup on Intel Macs via Homebrew follows exactly the same route. Only minor changes are required: 

• In the above instructions, when editing mame.ini, 

            always replace     /opt/homebrew/share/mame/

            by                         /usr/local/share/mame

          Of course, all respective subdirectories according to the instructions need to remain unchanged. 

• When copying the MAME Artwork with the Terminal Command, you must adjust it accordingly. 

Sorry for not repeating everything here from scratch again.

Technical Note: So you only need to change Homebrew paths of mame.ini because on Intel Macs, Homebrew installs into /usr/local/Homebrew, whereas onn ARM64 Macs, it installs into /opt/homebrew. The User Data part of the MAME installation is identical.

And MacPorts on Intel Macs - Nerd Stuff

On Intel Macs, MacPorts can be a real advantage, as support goes way back to very old MacOS versions. Out of curiosity, I completely uninstalled Homebrew and looked into the MacPorts MAME package - and I am truly impressed. Homebrew support for MAME ends with Sonoma.

Amazing MAME MacOS Support in MacPorts, there is even a Snow Leopard Version!

So if you are on an older Intel Mac, MacPorts could be the solution for you.

Same procedure as for Homebrew, but shortened, for details, please read the detailed steps above.

Step 0: I renamed my mame directory in $HOME/Library/Application Support/ in order to start fresh. Later on, we can still activate it.

Step 1: In a running MacPorts environment, this is: sudo port install mame

The MAME version 0.281 is a bit out of date by two versions. There is even a how-to for MAME in MacPorts: https://trac.macports.org/wiki/howto/Mame - however, the setup described here goes a bit further.

Step 2: In the empty Games/mame folder, I ran: mame -cc. It actually creates a better initial mame.ini file than Homebrew, but also plugin.ini. All necessary links into /opt/local/libexec/mame/ are created, even the BGFX path correctly puts into this place - very well done!

Steps 3 + 4: Then running mame from the Terminal within my Games/mame folder - it correctly creates the $HOME/Application Support/mame directory. So I will move my entire directory structure into this new folder - I only have do complete the newly created mame.ini file and move it there.

Stumbling Bock Artwork: The artwork directory in this MAME version is somehow hardcoded to /opt/local/libexec/mame/artwork - even different path designations in mame.ini are ignored. Placing custom artwork there is a no-go, as every update of MAME will replace this folder.

Acceptable workaround: 

• rename the original directory /opt/local/libexec/mame/artwork as you like
• make a symlink to your own artwork directory
• The catch: After each MAME Upgrade, MacPorts replaces your custom symlink with a new artwork directory. Therefore, the least thing to do is to re-implement the symlink after a MAME upgrade manually.

Nerd Zone: automatic symlink via a local Portfile (disclaimer - as explained to me by MS Copilot):

This script and local portfile runs a post-install script called reset-mame-artwork.sh and thereby re-implements the symlink automatically:

Step 1: Create an executable script called reset-mame-artwork.sh and make it executable:

#!/bin/zsh

# reset-mame-artwork.sh

# Renames original MacPorts artwork dir and replaces it with a symlink.

ORIG_DIR="/opt/local/libexec/mame/artwork"

BACKUP_DIR="/opt/local/libexec/mame/artwork.orig"

CUSTOM_DIR="/Users/stefanstockinger/Library/Application Support/mame/artwork"

# If original artwork dir exists and is not a symlink, rename it

if [ -d "$ORIG_DIR" ] && [ ! -L "$ORIG_DIR" ]; then

echo "Renaming original artwork directory to artwork.orig..."

sudo mv "$ORIG_DIR" "$BACKUP_DIR"

fi

# Remove any existing symlink or directory at artwork

if [ -e "$ORIG_DIR" ]; then

echo "Removing existing artwork entry..."

sudo rm -rf "$ORIG_DIR"

fi

# Create the symlink to your custom artwork folder

echo "Linking $CUSTOM_DIR to $ORIG_DIR..."

sudo ln -s "$CUSTOM_DIR" "$ORIG_DIR"

echo "Done. Artwork now points to $CUSTOM_DIR"

I can confirm that this script works perfectly if launched manually.

Step 2: Create a local Portfile for a post install procedure for this script and tell the MacPorts configuration about it (currently untested!)

In the Terminal, create a new folder for the local Portfile, e.g.

mkdir -p ~/macports-ports/emulators/mame 

Then copy the MAME portfile into this folder:

cp /opt/local/var/macports/sources/rsync.macports.org/macports/release/tarballs/ports/emulators/mame/Portfile ~/macports-ports/emulators/mame/

Edit the Portfile for MAME as follows (at the end, just above the notes):

post-activate {

    system "sudo /Users/stefanstockinger/bin/reset-mame-artwork.sh"

}

Then tell MacPorts about your local port, in the file /opt/local/etc/macports/sources.conf, edit the one line pointing to your local MAME Port:

file:///Users/YOURUSER/macports-ports
rsync://rsync.macports.org/macports/release/tarballs/ports.tar [default]

So sources.conf should contain these two lines. By putting your local folder above, it takes precedence.

Finally, make an update of MacPorts:

sudo port -v selfupdate

In overall, the results in MacPorts are very good, and with the artwork hack applied, it runs perfectly in MacOS.

Linux

Out of curiosity, I looked for Linux information, as it should set up similarly to MacOS. It seems that under Linux, MAME does not create a default User Data Directoy - you must create it manually. 

Still the basic ideas of this setup should apply as follows:

• Start the setup by installing MAME with your favorite package manager. Understand where the MAME binary is installed.
• Create your final MAME User Directory - best practice seems to be either $HOME/.mame or $HOME/.config/mame. 
• Execute mame from within your final MAME User Directory once for creating a fresh mame.ini.
• Create the necessary User Data directories, as shown above, in your final MAME User Directory and edit mame.ini accordingly.
• No idea whether the described Artwork problem for BGFX shaders also exist under Linux. When in doubt, also copy the artwork/bgfx folder to your User Directory and define one dedicated artwork path in mame.ini.

To-Do: Maybe look into MacPorts, at least for IntelMacs?