Skip to main content
Dolphin uses CMake for building on macOS. This guide covers both single-architecture and universal binary builds.

​
Prerequisites

​
Required Software

  • macOS: 11.0 Big Sur or later
  • Xcode: 14.3 or later
  • CMake: Version 3.20 or later
  • Git: For cloning the repository

​
Compiler Requirements

Dolphin requires AppleClang with C++23 support:
  • AppleClang: Version 14.0.3 or later (included in Xcode 14.3+)
CMake will inform you if your compiler version is insufficient.

​
Installing Dependencies

While many dependencies are bundled, some system libraries may improve build times: 
# Using Homebrew (optional)
brew install cmake git

​
Single-Architecture Build

Building for a single architecture (either x64 or ARM64) is the simplest approach.
1
Clone the Repository
2
git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin
3
Initialize Submodules
4
git submodule update --init --recursive
5
Failing to initialize submodules will cause build errors.
6
Create Build Directory
7
mkdir build
cd build
8
Configure with CMake
9
cmake ..
10
CMake will automatically detect your Mac’s architecture (Apple Silicon or Intel).
11
Build
12
make -j $(sysctl -n hw.logicalcpu)
13
This uses all available CPU cores for parallel compilation.
14
Locate the Application Bundle
15
After a successful build, the application bundle is created in:
16
./Binaries/Dolphin.app

​
Universal Binary Build

Universal binaries support both x64 (Intel) and ARM64 (Apple Silicon) in a single application bundle.
1
Clone the Repository
2
git clone https://github.com/dolphin-emu/dolphin.git
cd dolphin
3
Initialize Submodules
4
git submodule update --init --recursive
5
Create Build Directory
6
mkdir build
cd build
7
Run the Universal Build Script
8
python3 ../BuildMacOSUniversalBinary.py
9
The script will:
10
  • Create separate build directories for x64 and ARM64
  • Build both architectures
  • Combine them into a universal binary
    • 11
    Locate Universal Binaries
    12
    Universal binaries are created in:
    13
    ./universal/

    ​
    Universal Build Requirements

    Building universal binaries is more complex because it requires:
    • Library dependencies for both x64 and ARM64 architectures
    • OR universal library equivalents that support both architectures
    • Additional configuration for library locations
    If you have architecture-specific libraries installed, you may need to specify their locations using additional arguments.

    ​
    Universal Build Script Options

    View available options: 
    python3 ../BuildMacOSUniversalBinary.py --help
    Common options: 
    # Specify library paths for different architectures
python3 ../BuildMacOSUniversalBinary.py \
  --arm64-lib-path /opt/homebrew/lib \
  --x64-lib-path /usr/local/lib

    ​
    CMake Build Options

    Customize your macOS build with these options:

    ​
    Common Options

    # Release build (optimized, default)
cmake .. -DCMAKE_BUILD_TYPE=Release

# Debug build (with debug symbols)
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Release with debug info
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo

    ​
    Architecture-Specific Builds

    ​
    Building for Apple Silicon (ARM64)

    On an Apple Silicon Mac, CMake defaults to ARM64: 
    mkdir build
cd build
cmake ..
make -j $(sysctl -n hw.logicalcpu)

    ​
    Building for Intel (x64)

    On an Intel Mac, CMake defaults to x64: 
    mkdir build
cd build
cmake ..
make -j $(sysctl -n hw.logicalcpu)

    ​
    Cross-Compilation

    To build for a different architecture than your Mac: 
    # On Apple Silicon, build for Intel
cmake .. -DCMAKE_OSX_ARCHITECTURES=x86_64

# On Intel, build for Apple Silicon
cmake .. -DCMAKE_OSX_ARCHITECTURES=arm64
    Cross-compilation requires dependencies for the target architecture.

    ​
    Code Signing

    macOS requires code signing, especially on Apple Silicon Macs.

    ​
    Adhoc Signing (Default)

    Dolphin uses adhoc signing by default: 
    cmake .. -DMACOS_CODE_SIGNING=ON -DMACOS_CODE_SIGNING_IDENTITY="-"
    This is sufficient for local development and testing.

    ​
    Developer ID Signing

    For distribution: 
    cmake .. \
  -DMACOS_CODE_SIGNING=ON \
  -DMACOS_CODE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"

    ​
    Disabling Code Signing

    Disabling code signing will prevent Dolphin from running on Apple Silicon Macs.
    cmake .. -DMACOS_CODE_SIGNING=OFF

    ​
    Advanced Build Scenarios

    ​
    Bundle Postprocessing

    For redistributable builds: 
    cmake .. -DPOSTPROCESS_BUNDLE=ON
    This ensures all dependencies are properly bundled within the app.

    ​
    Custom Deployment Target

    Change the minimum macOS version: 
    cmake .. -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0
    Default is macOS 11.0 (Big Sur). Enable LTO for better performance: 
    cmake .. -DENABLE_LTO=ON

    ​
    Troubleshooting

    ​
    Xcode Version Too Old

    Error: CMake reports AppleClang version is too old Solution: Update Xcode through the Mac App Store or download from Apple Developer. Minimum requirement: Xcode 14.3 (AppleClang 14.0.3)

    ​
    Submodules Not Initialized

    Error: Missing header files from Externals Solution: 
    git submodule update --init --recursive

    ​
    Code Signing Errors on Apple Silicon

    Error: Binary won’t run on Apple Silicon Solution: Ensure code signing is enabled: 
    cmake .. -DMACOS_CODE_SIGNING=ON
make -j $(sysctl -n hw.logicalcpu)

    ​
    Universal Binary Build Fails

    Error: Missing libraries for one architecture Solution: Universal builds require dependencies for both architectures. Either:
    1. Install universal versions of dependencies
    2. Install separate versions for each architecture and specify paths:
    python3 ../BuildMacOSUniversalBinary.py \
  --arm64-lib-path /opt/homebrew/lib \
  --x64-lib-path /usr/local/lib

    ​
    MoltenVK Issues

    Error: Vulkan backend not working Solution: Ensure bundled MoltenVK is enabled: 
    cmake .. -DUSE_BUNDLED_MOLTENVK=ON

    ​
    Build Errors After Git Pull

    Solution: Clean and rebuild: 
    cd build
rm -rf *
git submodule update --init --recursive
cmake ..
make -j $(sysctl -n hw.logicalcpu)

    ​
    Library Path Issues

    Error: CMake can’t find certain libraries Solution: If using Homebrew, library paths differ by architecture:
    • Apple Silicon: /opt/homebrew/
    • Intel: /usr/local/
    Specify the correct path: 
    cmake .. -DCMAKE_PREFIX_PATH=/opt/homebrew

    ​
    Running the Built Application

    ​
    From Build Directory

    open ./Binaries/Dolphin.app

    ​
    From Command Line

    ./Binaries/Dolphin.app/Contents/MacOS/Dolphin

    ​
    Installing to Applications

    cp -r ./Binaries/Dolphin.app /Applications/

    ​
    Uninstalling

    To uninstall Dolphin: 
    # Remove application
rm -rf /Applications/Dolphin.app

# Remove user data (optional)
rm -rf ~/Library/Application\ Support/Dolphin

    ​
    Next Steps

    After building:
    • The application bundle is ready to use in Binaries/Dolphin.app
    • User data is stored in ~/Library/Application Support/Dolphin/
    • For distribution, consider bundle postprocessing and proper code signing
    For universal binaries intended for distribution, use the universal build script and enable bundle postprocessing.