System Requirements
Before installing Hydra, ensure your Mac meets these requirements:
Hardware Requirements
- CPU: Intel or Apple Silicon processor
- Apple Silicon (M1/M2/M3) recommended for best performance
- Intel Macs supported but with lower performance
- RAM: 4GB minimum, 8GB or more recommended
- GPU: Metal-compatible graphics card (all Macs from 2012 onward)
- Storage:
- 500MB for the emulator
- Additional space for games and firmware
- SSD recommended for faster load times
Software Requirements
- Operating System: macOS 10.15 (Catalina) or later
- macOS 12 (Monterey) or later recommended
- Xcode Command Line Tools (for building from source)
Installation Methods
Download Pre-built Binary
The easiest way to get started is to download a pre-built release.Extract the Archive
Double-click the downloaded .zip or .dmg file to extract Hydra.app.
Move to Applications
Drag Hydra.app to your /Applications folder (optional but recommended).
First Launch
Right-click on Hydra.app and select Open to bypass macOS Gatekeeper if the app is not notarized.On first launch, macOS may show a security warning. Click Open in the dialog to proceed.
~/Library/Application Support/Hydra/
Build from Source
Building from source gives you access to the latest features and allows you to customize the build.Install Dependencies
Install the required dependencies using Homebrew:brew install cmake ninja sdl3 fmt
If you don’t have Homebrew installed, get it from brew.sh. Clone the Repository
Clone the Hydra repository and initialize submodules:git clone https://github.com/SamoZ256/hydra.git
cd hydra
git submodule update --init --recursive
The --recursive flag is important - it ensures all required submodules are downloaded.
Configure CMake
Configure the build with CMake:cmake . -B build -G Ninja -DMACOS_BUNDLE=ON
MACOS_BUNDLE=ON - Build a macOS app bundleFRONTEND=SwiftUI - Use SwiftUI instead of SDL3HYPERVISOR_ENABLED=OFF - Disable Apple Hypervisor backendCUBEB_ENABLED=OFF - Disable Cubeb audio backend
Build with Ninja
Compile the project:This will take several minutes depending on your Mac’s performance. Locate the Built App
After building, you’ll find the app at:You can launch it directly or copy it to your Applications folder:cp -r build/bin/Hydra.app /Applications/
Firmware Setup
Many official Nintendo Switch games require system firmware files to run properly.
You must dump firmware files from your own Nintendo Switch console. Hydra requires decrypted firmware files.
Obtain Firmware Files
Firmware files must be dumped from a Nintendo Switch console and decrypted. You can use tools like switch-extract-macos to decrypt firmware.Hydra does not include firmware files. You must provide your own legally obtained firmware.
Place Firmware Files
Copy your decrypted firmware files to a location on your Mac, such as:~/Documents/Switch/Firmware/
Configure Firmware Path
Launch Hydra at least once to generate the configuration file, then edit:~/Library/Application Support/Hydra/config.toml
[System]
firmware_path = "/Users/YOUR_USERNAME/Documents/Switch/Firmware"
YOUR_USERNAME with your actual macOS username. Game Patches
Official games often require patches to prevent crashes and improve compatibility.
Follow Patch Guide
The patches repository includes detailed instructions on installing and configuring patches for specific games.
Directory Structure
After installation and first launch, Hydra creates the following directories:
~/Library/Application Support/Hydra/
├── config.toml # Main configuration file
├── sdmc/ # Virtual SD card storage
├── save/ # Game save data
└── sysmodules/ # System modules
~/Library/Logs/Hydra/ # Log files
Verifying Installation
To verify Hydra is installed correctly:
Launch the Emulator
Double-click Hydra.app to launch the emulator.
Check Configuration File
Verify that the configuration file was created:ls ~/Library/Application\ Support/Hydra/config.toml
Review Settings
Open the config file to review default settings:cat ~/Library/Application\ Support/Hydra/config.toml
- NRO - Nintendo Relocatable Object (homebrew)
- NCA - Nintendo Content Archive (official games)
- NX - Alternative packaged format
- NSO - Nintendo Shared Object
Uninstallation
To completely remove Hydra from your Mac:
Delete the Application
rm -rf /Applications/Hydra.app
Remove User Data
rm -rf ~/Library/Application\ Support/Hydra
rm -rf ~/Library/Logs/Hydra
This will delete all save data and configuration. Back up any important saves first.
Next Steps
Quick Start
Load and run your first game
Configuration Guide
Customize CPU, GPU, and display settings
Firmware Setup
Learn more about firmware requirements
Troubleshooting
Fix common installation issues