A powerful, Terminal Based mod manager for Bethesda games on Linux
Features • Installation • Quick Start • Contributing • Donate
If you find this tool useful, consider showing your support with a donation. Obviously not a requirement, but a little goes a long way towards future development
ModSanity is a native Linux mod manager built from the ground up for Bethesda games. Designed for power users who prefer terminal workflows, it combines the full feature set of tools like Mod Organizer 2 and Vortex with the speed and efficiency of a Terminal TUI.
Why ModSanity?
- Linux-native: Built specifically for Linux with first-class Steam/Proton support
- Terminal Based: Complete TUI interface with vim-style navigation
- Zero compromise: Full FOMOD installer support, conflict detection, and profile management
- Fast & efficient: Written in Rust for maximum performance
- Safe & deterministic: Transactional deployments with automatic rollback
- Just works: Automatic game detection, intelligent mod categorization
- Automatic game detection for Steam libraries including Proton prefixes
- Multi-game support for Bethesda Creation Engine titles
- Intelligent path resolution for Windows games running under Proton
- Tested with Skyrim SE, Skyrim VR, and designed for Fallout 4, Oblivion, and more
- Full FOMOD installer support with interactive wizard interface
- Multi-step installations with conditional logic
- Option flags and dependency resolution
- Preview and rollback capabilities
- Persistent installer choices per profile
- Priority-based load ordering with automatic conflict resolution
- Smart conflict detection showing file overwrites before deployment
- Auto-categorization using mod metadata and file structure analysis
- Multiple deployment methods: symlinks, hardlinks, or file copies
- Archive support: ZIP, 7-Zip with automatic extraction
- Unlimited profiles for different playthroughs or testing
- Per-profile FOMOD installations for variant mod setups
- Instant switching between mod configurations
- Isolated plugin load orders per profile
- LOOT-compatible sorting with masterlist integration
- Dependency resolution ensuring masters load correctly
- Group-based ordering for optimal plugin arrangement
- Manual override support for fine-tuning
- ESP/ESM/ESL support with proper flag handling
- Direct mod browsing from the TUI
- Search functionality across all game mods
- One-click downloads with progress tracking
- Mod metadata sync including descriptions and requirements
- Requirement checking via NexusMods API
- Personal API key and SSO support (experimental)
- Interactive terminal UI built with Ratatui
- Keyboard navigation (vim-style keybindings supported)
- Real-time status updates during operations
- Context-sensitive help with
?key - Multi-screen workflow: Mods, Plugins, Downloads, Profiles, Settings
- CLI mode for scripting and automation
- JSON/YAML/TOML configuration support
- Comprehensive logging with tracing support
- SQLite database for fast queries
- Modular architecture with clean APIs
# Clone the repository
git clone https://github.com/modsanity/modsanity.git
cd modsanity
# Build release binary
cargo build --release
# Install to ~/.local/bin (or your preferred location)
cp target/release/modsanity ~/.local/bin/
# Or run the install script
./install.shDownload the latest binary from the Releases page.
# Make executable
chmod +x modsanity
# Move to PATH
mv modsanity ~/.local/bin/Detect your games:
modsanity game scan # Scan Steam libraries
modsanity game list # View detected games
modsanity game select skyrimse # Set active gameOption A - Personal API Key (for testing):
modsanity nexus set-api-key YOUR_API_KEYGet your API key at: https://www.nexusmods.com/users/myaccount?tab=api
Option B - TUI Setup:
- Launch TUI:
modsanity - Press
F4for Settings - Select "NexusMods API Key"
- Paste your key
modsanity
# or explicitly
modsanity tuiVia NexusMods (in TUI):
- Press
bto browse NexusMods - Press 's' to search from the browse window
- Select a mod and download
- Press
ito install from downloads
Via Local Archive:
modsanity mod install path/to/mod.zip
# or in TUI: press 'i' and select filemodsanity deploy
# or in TUI: press 'D' on the Mods screen| Key | Action |
|---|---|
F1 |
Mods screen |
F2 |
Plugins screen |
F3 |
Profiles screen |
F4 |
Settings screen |
g |
Game selection |
? |
Toggle help overlay |
q / Ctrl+C |
Quit |
| Key | Action |
|---|---|
↑/k ↓/j |
Navigate mods |
Space / e |
Enable/disable mod |
+ / = |
Increase priority (loads later) |
- |
Decrease priority |
i |
Install mod from archive |
d / Delete |
Delete mod (with confirmation) |
D |
Deploy all enabled mods |
/ |
Search/browse NexusMods |
r |
Refresh mod list |
x |
Check mod requirements |
| Key | Action |
|---|---|
Space / e |
Enable/disable plugin |
s |
Save and optimize load order |
↑/k ↓/j |
Navigate plugins |
| Key | Action |
|---|---|
Enter |
Switch to profile |
n |
Create new profile |
d / Delete |
Delete profile |
| Key | Action |
|---|---|
Enter |
Download selected mod |
/ |
Search NexusMods |
r |
Refresh/load top mods |
modsanity game list # List detected games
modsanity game scan # Scan for games
modsanity game select <name> # Select active game
modsanity game info # Show active game infomodsanity mod list # List installed mods
modsanity mod install <path> # Install mod from archive
modsanity mod enable <name> # Enable a mod
modsanity mod disable <name> # Disable a mod
modsanity mod remove <name> # Remove a mod
modsanity mod info <name> # Show mod detailsmodsanity profile list # List profiles
modsanity profile create <name> # Create new profile
modsanity profile switch <name> # Switch to profile
modsanity profile delete <name> # Delete profile
modsanity profile export <name> <path> # Export profile
modsanity profile import <path> # Import profilemodsanity nexus set-api-key <key> # Set personal API key
modsanity nexus login # Login via SSO
modsanity nexus logout # Logout
modsanity nexus search <query> # Search for mods
modsanity nexus download <mod_id> # Download a mod
modsanity nexus status # Show account statusmodsanity deploy # Deploy mods to game directory
modsanity status # Show current statusModSanity includes full MO2/Vortex-grade FOMOD support, built from the ground up for Linux:
- Complete XML parsing of
ModuleConfig.xmlandinfo.xml - Multi-step installations with pages and groups
- Conditional logic with flag evaluation
- Requirement validation (SelectExactlyOne, SelectAtMostOne, etc.)
- File mapping and custom install paths
- Conflict preview before installation
- Transactional execution with automatic rollback on failure
- Persistent choices - rerun installers with saved selections
- Per-profile installations - different FOMOD configs per profile
- Install a FOMOD-enabled mod
- ModSanity auto-detects the installer
- Launch the interactive wizard (in TUI or via CLI)
- Navigate through steps, select options
- Preview file operations and conflicts
- Confirm and install with rollback safety
For details, see FOMOD_USER_GUIDE.md.
- Transactional deployments: All-or-nothing installations with automatic rollback
- Priority-based conflict resolution: Explicit, reproducible load orders
- No hidden state: Always preview what files will be deployed
- Atomic operations: Safe profile switching and mod updates
- Async I/O: Fast downloads and file operations
- SQLite caching: Quick queries for large mod lists
- Efficient algorithms: Topological sorting for plugin load orders
- Minimal overhead: Direct symlinks avoid file duplication
src/
├── games/ # Game detection and configuration
├── mods/ # Mod management and FOMOD
├── plugins/ # Plugin load order and LOOT integration
├── profiles/ # Profile management
├── nexus/ # NexusMods API client
├── db/ # Database layer
├── config/ # Configuration handling
└── tui/ # Terminal UI
- Config file:
~/.config/modsanity/config.toml - Data directory:
~/.local/share/modsanity/ - Mod storage:
~/.local/share/modsanity/games/<game_id>/mods/
Configure in config.toml:
[deployment]
method = "symlink" # Options: "symlink", "hardlink", "copy"- symlink: Fast, space-efficient (recommended)
- hardlink: Safe for games that follow symlinks
- copy: Full file copies (most compatible, uses more space)
Currently tested with:
- The Elder Scrolls V: Skyrim Special Edition
- The Elder Scrolls V: Skyrim VR
Designed to work with all Creation Engine games:
- Fallout 4
- Fallout: New Vegas
- The Elder Scrolls IV: Oblivion
- Fallout 3
- Starfield
Community testing and contributions welcome for additional games!
- NexusMods SSO: Requires official app registration (use personal API key for now)
- Windows-only mods: Some tools with native Windows executables won't work (use Proton workarounds)
- Early development: Some edge cases may not be handled perfectly
Contributions are welcome! Here's how you can help:
- Report bugs: Open an issue with details and reproduction steps
- Suggest features: Describe your use case and desired functionality
- Test new games: Try ModSanity with other Bethesda titles and report results
- Submit PRs: Fix bugs, add features, or improve documentation
git clone https://github.com/modsanity/modsanity.git
cd modsanity
cargo build
cargo test- Follow Rust conventions (
cargo fmt,cargo clippy) - Add tests for new features
- Update documentation for user-facing changes
ModSanity is licensed under the MIT License.
- LOOT - Load order optimization algorithms and masterlist format
- Mod Organizer 2 - FOMOD specification and mod management patterns
- Ratatui - Excellent terminal UI framework
- NexusMods - API and mod hosting infrastructure
- Bethesda modding community - For decades of incredible content
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Collections support (Nexus Collections integration)
- Download queue management
- Mod update notifications
- BSA/BA2 archive extraction
- Integrated conflict resolver UI
- Web UI (optional companion to TUI)
- Cloud profile sync
- Mod dependency graph visualization
- xEdit integration for conflict detection
- SKSE/F4SE version management
- GUI version (GTK/Qt)
- Windows/macOS support
- Integration with other mod sites (ModDB, LoversLab, etc.)
- Advanced scripting and automation APIs