switch-up

A safe, automated SD card manager for Nintendo Switch homebrew on macOS, Windows, and Linux.

Why does this exist?

switch-up started as a fix for the very real problems macOS causes when updating a Switch SD card.

macOS silently injects hidden files (.DS_Store, ._* files, extended attributes) into folders on FAT32/exFAT media. Those files can corrupt your SD card from the Switch's point of view and trigger boot failures, black screens, and cryptic errors.

On top of that, macOS Finder's "Replace" behavior is destructive — dragging a folder with the same name can delete the original instead of merging contents. A simple update can wipe out configs, mods, cheats, and homebrew files.

Even on Windows and Linux, users still benefit from a safer update flow.

switch-up automates the process safely:

1. Backs up your configuration files before touching anything
2. Smart Merges new files onto your SD without deleting existing content
3. Cleans hidden junk files that should not live on the SD card
4. Restores your backup automatically if anything goes wrong

Installation

From PyPI

pip install switch-up

From source

git clone https://github.com/yourusername/switch-up.git
cd switch-up
pip install -e .

Requirements

• Python 3.8 or higher
• macOS, Windows, or Linux

Usage

Update Atmosphere and Hekate to the latest version

Downloads the latest releases from GitHub and installs them safely to your SD card.

switch-up update --latest

The tool will auto-detect your SD card from the default mount locations of the current platform:

• macOS: /Volumes
• Linux: /media, /run/media, /mnt
• Windows: mounted drive letters such as E:/

If you have multiple SD cards or a custom mount point, specify the path manually:

switch-up update --latest --sd-path /path/to/your/sd

Examples:

switch-up update --latest --sd-path /Volumes/MY_SD
switch-up update --latest --sd-path /media/oscar/MY_SD
switch-up update --latest --sd-path E:/

Update only Atmosphere (skip Hekate)

switch-up update --latest --ams-only

Install a local ZIP file

If you already downloaded a release ZIP manually:

switch-up install ./atmosphere-1.8.0.zip --sd-path /path/to/your/sd

Clean junk files only (no update)

Removes hidden compatibility junk from the SD card. On macOS this also attempts to remove extended attributes.

switch-up fix-archive-bit /path/to/your/sd

What happens during an update?

1. Backup      → Saves hekate_ipl.ini, exosphere.ini, and other configs
                  to ~/.switch-up/backups/ (timestamped)
2. Extract     → Unpacks the ZIP to a temporary directory
3. Smart Merge → Copies new files to SD, preserving your existing content
4. Cleanup     → Removes .DS_Store, ._* files, __MACOSX/, and xattrs on macOS
5. Done        → If anything fails at step 3, your backup is auto-restored

Configuration Backups

Before every operation, switch-up saves your critical config files to:

~/.switch-up/backups/20260227_143000/
├── hekate_ipl.ini
├── exosphere.ini
├── bootloader/hekate_ipl.ini
└── atmosphere/config/system_settings.ini

These backups persist across sessions so you can always recover your settings.

Commands Reference

Platform Support

switch-up now supports macOS, Windows, and Linux.

Current behavior by platform

• macOS

  • Auto-detects SD cards under /Volumes
  • Removes hidden junk files
  • Removes extended attributes when possible

• Linux

  • Auto-detects SD cards under /media, /run/media, and /mnt
  • Supports backup, Smart Merge, local ZIP install, and release downloads
  • Skips macOS-only xattr cleanup

• Windows

  • Auto-detects SD cards from mounted drive letters
  • Supports backup, Smart Merge, local ZIP install, and release downloads
  • Skips macOS-only xattr cleanup

License

GPLv3 — See LICENSE for details.