Skip to main content
Hydra stores its configuration in a TOML file located at:
  • macOS: ~/Library/Application Support/Hydra/config.toml
  • Linux: ~/.config/Hydra/config.toml
  • Windows: %APPDATA%/Hydra/config.toml
You can configure Hydra through the Settings window (⌘+, on macOS) or by directly editing the configuration file.

​
Configuration Categories

​
Game Paths

Specify directories where Hydra should search for games.
[General]
game_paths = [
  "/Users/username/Games/Switch",
  "/Volumes/External/Switch Games"
]
Supported locations:
  • Folders containing game files
  • Individual game files (.nro, .nca, etc.)

​
Loader Plugins

Extend Hydra’s game loading capabilities with plugins.
[[General.loader_plugins]]
path = "/path/to/plugin.dylib"

  [General.loader_plugins.options]
  option_key = "value"

​
Patch Paths

Directories containing game patches and mods.
patch_paths = [
  "/Users/username/Hydra/patches"
]

​
CPU Backend

Hydra supports two CPU emulation backends:The backend is automatically selected based on your platform and availability.

​
GPU Renderer

Currently, Hydra only supports Metal rendering on macOS:
[Graphics]
renderer = "Metal"

​
Shader Backend

Choose how shaders are compiled:

​
Display Resolution

Control the rendering resolution:
display_resolution = "auto"  # Recommended
Available options:
  • "auto" (recommended) - Automatically scales based on game and display
  • "720p" - 1280x720
  • "1080p" - 1920x1080
  • "1440p" - 2560x1440
  • "2160p" - 3840x2160 (4K)
  • "4320p" - 7680x4320 (8K)
  • "Auto exact" - Matches game’s native resolution exactly
  • "custom" - Specify custom resolution

​
Custom Resolution

When using custom resolution mode:
display_resolution = "custom"
custom_display_resolution = "2560x1440"
Custom resolutions are not recommended and may cause graphical issues or performance problems.

​
Audio Backend

Select the audio output backend:

​
User ID

Each user profile has a unique ID for save data management:
[User]
user_id = 0
User profiles can be managed through the User settings tab. Each user can have custom avatars and nicknames.

​
File Paths

Configure system-level paths:
[System]
firmware_path = "/path/to/firmware"
sd_card_path = "~/Library/Application Support/Hydra/sdmc"
save_path = "~/Library/Application Support/Hydra/save"
sysmodules_path = "~/Library/Application Support/Hydra/sysmodules"
Path descriptions:
  • firmware_path - Directory containing Switch firmware files (*.nca)
  • sd_card_path - Virtual SD card storage
  • save_path - Game save data location
  • sysmodules_path - System modules directory
SD card, save, and sysmodules paths are automatically created with default locations if not specified.

​
Operation Mode

handheld_mode = true
Set to false for docked mode. You can toggle this during emulation with ⌘+O.

​
Logging

Control log output:
[Debug]
log_output = "file"  # Default
log_fs_access = false
debug_logging = false
Log output options:
  • "file" - Logs saved to ~/Library/Logs/Hydra/ (macOS)
  • "stdout" - Print logs to console
  • "none" - Disable logging (not recommended)
Setting log_output to “none” will make troubleshooting very difficult.

​
Error Handling

recover_from_segfault = false
Enable to attempt recovery from segmentation faults (experimental).

​
GDB Support

Enable GDB debugging for development:
gdb_enabled = false
gdb_port = 1234
gdb_wait_for_client = false
GDB support is intended for emulator developers and requires connecting a GDB client to debug emulated code.

​
Process Arguments

Pass custom arguments to emulated processes:
process_args = []

​
Configuration File Locations

# Config file
~/Library/Application Support/Hydra/config.toml

# Logs
~/Library/Logs/Hydra/

# Screenshots
~/Pictures/Hydra/

​
Resetting Configuration

To reset Hydra to default settings:
  1. Close Hydra completely
  2. Delete or rename config.toml
  3. Restart Hydra (a new default config will be created)
This will reset all settings including game paths, graphics options, and user preferences.

Build docs developers (and LLMs) love

Get started for freeTalk to us