Skip to content

GUIDE.md

Latest commit

 

History

History
422 lines (262 loc) · 15.2 KB

GUIDE.md

File metadata and controls

422 lines (262 loc) · 15.2 KB

Beginner's Guide

A step-by-step walkthrough for downloading and managing Nexus Mods collections on Linux. No prior command-line experience required - every command is copy-pasteable with an explanation of what it does.

What this tool does

nexus-dl lets you download entire mod collections from Nexus Mods on Linux. Collections are curated mod packs that other players put together - think of them as "mod playlists" where someone has already figured out which mods work well together and in what order they should load.

Normally, downloading collections requires Vortex or the Nexus Mods app, which only run on Windows. This tool does the same thing from a Linux terminal (or from a local web page in your browser if you prefer clicking over typing).

It works with any game on Nexus Mods - Baldur's Gate 3, Starfield, Cyberpunk 2077, Skyrim, Stardew Valley, and everything else.

What you need before starting

  1. A Nexus Mods account - Both free and Premium accounts work. Premium lets the tool download files automatically. Free accounts work too - you just download the files yourself through the browser and the tool handles everything else (metadata, extraction, load order). More on this below.

  2. Python 3.10 or newer - This comes pre-installed on most Linux distributions. We'll check in a moment.

  3. A Nexus Mods API key - This is a secret code that lets the tool talk to Nexus Mods on your behalf. We'll get this together below.

  4. git - Used to download the tool itself. Also pre-installed on most systems.

Opening a terminal

A terminal is a text window where you type commands. Here's how to open one:

  • Ubuntu / Pop!_OS / Linux Mint: Press Ctrl + Alt + T
  • Fedora / GNOME: Press Super (the Windows key), type "Terminal", and click it
  • KDE (Kubuntu, Fedora KDE): Press Ctrl + Alt + T, or find "Konsole" in your app menu
  • Steam Deck (Desktop Mode): Tap the Steam icon in the taskbar, go to System > Konsole. Or find "Konsole" in the app launcher.

You should see a window with a blinking cursor. That's where you'll type the commands from this guide.

Checking Python

Copy and paste this into your terminal, then press Enter:

python3 --version

You should see something like Python 3.12.3. Any version 3.10 or higher works.

If you get "command not found":

# Ubuntu/Debian/Pop!_OS
sudo apt install python3 python3-venv python3-pip

# Fedora
sudo dnf install python3

# Steam Deck - Python is pre-installed, but if missing:
sudo pacman -S python

Installing nexus-dl

These commands download the tool and set it up. Run them one at a time:

git clone https://github.com/scottmccarrison/nexus-collection-dl.git

This downloads the tool's code into a folder called nexus-collection-dl.

cd nexus-collection-dl

This moves you into that folder.

./setup.sh

This installs everything the tool needs. It creates an isolated environment (called a "virtual environment") so it won't interfere with anything else on your system. It takes a minute or two.

source venv/bin/activate

This activates the tool's environment. You'll notice your terminal prompt changes - it'll show (venv) at the beginning. You need to run this command every time you open a new terminal before using nexus-dl. (We'll cover how to make this automatic later.)

Verify it worked:

nexus-dl --help

You should see a list of commands like sync, update, deploy, etc. The tool also checks for newer versions automatically - if an update is available, you'll see a notice when you run any command.

Getting your API key

An API key is like a password that lets the tool talk to Nexus Mods on your behalf.

  1. Go to nexusmods.com and log in
  2. Click your profile picture in the top right
  3. Click Site preferences
  4. Click the API Keys tab
  5. Under "Personal API Key", type a name for the key (anything works - "nexus-dl" is fine)
  6. Click Request an API key
  7. Copy the long string of letters and numbers that appears

Keep this key private. Treat it like a password - don't share it or post it publicly.

Setting your API key

The tool looks for your API key in an "environment variable" called NEXUS_API_KEY. An environment variable is just a named value that programs can read.

Quick method (lasts until you close the terminal)

export NEXUS_API_KEY="paste-your-key-here"

Replace paste-your-key-here with the key you copied. Keep the quotes.

Permanent method (recommended)

To avoid setting the key every time you open a terminal, add it to your shell's startup file:

echo 'export NEXUS_API_KEY="paste-your-key-here"' >> ~/.bashrc

Replace paste-your-key-here with your actual key. Then reload the file:

source ~/.bashrc

Now the key will be set automatically every time you open a terminal.

Note: If your terminal uses zsh instead of bash (you can check with echo $SHELL), use ~/.zshrc instead of ~/.bashrc.

Your first download

Finding a collection URL

  1. Go to nexusmods.com
  2. Pick a game (e.g., Baldur's Gate 3)
  3. Click the Collections tab on the game's page
  4. Browse or search for a collection you like
  5. Click on it to open the collection page
  6. Copy the URL from your browser's address bar - it looks something like: https://next.nexusmods.com/baldursgate3/collections/abc123

Downloading

Make sure you're in the nexus-collection-dl directory and have the virtual environment activated (you should see (venv) in your prompt). Then:

nexus-dl sync "https://next.nexusmods.com/baldursgate3/collections/abc123" ~/mods/bg3

Replace the URL with the one you copied, and bg3 with whatever game abbreviation you like (it's just a folder name).

What this does:

  • Contacts Nexus Mods to get the list of mods in the collection
  • Downloads each mod file
  • Extracts archives (ZIP, 7z, RAR)
  • Generates a load order so mods load in the right sequence
  • Saves everything to ~/mods/bg3 (a "mods" folder in your home directory)

Each collection gets its own named subfolder inside the mods directory, so you can sync multiple collections for the same game without them mixing together.

This can take a while depending on how many mods are in the collection. You'll see progress as each mod downloads. If you need to stop partway through, that's fine - re-running sync picks up where you left off, skipping mods that were already downloaded.

Skipping optional mods

Some collections mark certain mods as optional. To skip those:

nexus-dl sync --skip-optional "https://next.nexusmods.com/baldursgate3/collections/abc123" ~/mods/bg3

File conflicts

After sync (and deploy), the tool checks for file conflicts - cases where two or more mods include the same file. If any are found, you'll see a summary listing which files overlap and which mods are involved. This is informational - the tool still works, but it helps you understand when one mod's files are being overwritten by another.

If you have a free account

If you don't have Nexus Mods Premium, the tool does everything except the actual file download. You download the mod files yourself through the browser (Nexus shows a countdown timer for free downloads), and the tool handles the rest: figuring out which mods to get, where to find them, extracting archives, generating load order, tracking state, and deployment. Once files are local, everything works identically to Premium.

Step 1: Sync the collection

Run the same sync command as Premium users:

nexus-dl sync "https://next.nexusmods.com/baldursgate3/collections/abc123" ~/mods/bg3

The tool fetches the collection metadata, caches the manifest for load order generation, and shows you a table with each mod's name, filename, and a clickable URL:

Pending Downloads (manual)
Mod                  | Filename              | Size    | URL
Script Extender      | ScriptExtender-v2.zip | 12.3 MB | https://www.nexusmods.com/baldursgate3/mods/...
Better UI            | BetterUI-1.5.pak      | 4.1 MB  | https://www.nexusmods.com/baldursgate3/mods/...
...

Free account detected. Download the files above through your browser, save them to ~/mods/bg3, then run:
  nexus-dl import ~/mods/bg3

Step 2: Download the files

Click each URL. Nexus Mods will show its standard free download page with a countdown timer. When the download starts, save the file to your mods directory (~/mods/bg3 in this example). Keep the original filename - the tool matches files by name.

Tip: You don't have to download everything at once. Download a few, run import, download more later - the tool tracks what's done and what's still pending.

Step 3: Import

Once you've downloaded some or all of the files:

nexus-dl import ~/mods/bg3

This scans the mods directory for files matching the pending downloads, extracts archives, updates the state, and regenerates load order. If some files are still missing, it tells you which ones.

Step 4: Deploy

Once all mods are imported (or whenever you're ready), deploy as usual:

nexus-dl deploy ~/mods/bg3

Everything works identically to Premium from here on - status, updates, undeploy, tracked mods, etc.

Checking what's still pending

nexus-dl status ~/mods/bg3

Mods you haven't downloaded yet show as "Pending download" in yellow.

Checking status

To see what's installed and whether any mods have updates available:

nexus-dl status ~/mods/bg3

This reads the local state file - it doesn't download anything.

Updating mods

When mod authors release updates, you can pull them in:

nexus-dl update ~/mods/bg3

This checks each mod against Nexus, downloads anything that has a newer version, and regenerates the load order.

To preview what would change without actually downloading:

nexus-dl update --dry-run ~/mods/bg3

Deploying to your game

Downloading mods is only half the job - the game needs to find them. The deploy command puts the mod files where the game expects them.

nexus-dl deploy ~/mods/bg3

If the game was installed through Steam, the tool auto-detects the game directory. If not (or if auto-detection fails), specify it manually:

nexus-dl deploy ~/mods/bg3 --game-dir /path/to/your/game/install

You only need to specify --game-dir once. The tool remembers it for future deploys.

What "deploying" actually does

The tool creates symlinks (shortcuts) from your mod staging directory into the game's install directory. The original mod files stay in ~/mods/bg3, but the game sees them as if they're in its own folder.

This means:

  • Mod files aren't duplicated (saves disk space)
  • You can "undeploy" cleanly at any time
  • Updating mods automatically updates what the game sees

Preview before deploying

nexus-dl deploy --dry-run ~/mods/bg3

This shows what files would be placed where, without actually doing anything.

Removing deployed mods

To undo a deployment and restore your game directory:

nexus-dl undeploy ~/mods/bg3

Using the web UI

If you do not want to memorize terminal commands, the web UI is probably the better option for day-to-day mod management. The CLI is faster for one-off operations and scripting, but the web UI lets you do almost everything from a browser with real-time progress feedback.

To start it:

nexus-dl serve ~/mods/bg3

Then open your browser to http://127.0.0.1:5000. To use a different port:

nexus-dl serve ~/mods/bg3 --port 8080

What you get

The web UI has two pages:

Dashboard - Shows your collection at a glance: collection name, game, installed revision, how many mods, whether updates are available, and deployment status. From here you can sync a collection (paste the URL into a text box), update, deploy, undeploy, regenerate the load order, and manage tracked-mod sync. All with buttons instead of commands.

Mods - Lists every installed mod with status badges (up to date, update available, removed from collection, manual, etc.), version numbers, and load phases. You can add a mod by URL or register a local mod from this page.

Real-time progress

Long-running operations (syncing a big collection, downloading updates) stream progress to the browser in real time. You will see a progress bar and status messages as each mod downloads. This is one area where the web UI is nicer than the CLI, which just prints log lines.

CLI vs. web UI

Both interfaces share the same code underneath, so the results are identical. The main differences:

  • The CLI has --dry-run for deploy and update (preview without acting). The web UI does not.
  • The CLI has --no-load-order and --prefix flags for more granular control.
  • The web UI shows progress bars and visual status badges. The CLI prints text.

If you are just getting started, the web UI is the easier path. You only need the terminal to run nexus-dl serve and then everything else happens in the browser.

Press Ctrl + C in the terminal to stop the web server when you are done.

The --no-extract flag

If you use a mod manager like Stardrop (for Stardew Valley) or another tool that expects raw archive files instead of extracted folders, use the --no-extract flag:

nexus-dl sync --no-extract "https://next.nexusmods.com/stardewvalley/collections/abc123" ~/mods/stardew

This downloads the mod archives but leaves them as .zip, .7z, or .rar files instead of extracting them. Your mod manager can then handle extraction and installation its own way.

The flag also works with update:

nexus-dl update --no-extract ~/mods/stardew

Troubleshooting

"python3: command not found"

Python isn't installed. See the Checking Python section above for install commands.

"nexus-dl: command not found"

You probably need to activate the virtual environment:

cd ~/nexus-collection-dl
source venv/bin/activate

If that doesn't work, try re-running ./setup.sh.

"Permission denied" when running setup.sh

The setup script needs execute permission:

chmod +x setup.sh
./setup.sh

"unrar: command not found" during sync

Some mods are packed as RAR archives. Install the unrar tool:

# Ubuntu/Debian
sudo apt install unrar

# Fedora
sudo dnf install unrar

Rate limiting / "429 Too Many Requests"

Nexus Mods limits how many requests you can make per hour. If you hit this, wait a few minutes and try again. The tool handles rate limits automatically in most cases, but very large collections might need a retry.

"NEXUS_API_KEY not set"

You need to set your API key. See Setting your API key above. If you set it with the permanent method, make sure you ran source ~/.bashrc or opened a new terminal.

Mods downloaded but game doesn't see them

You need to deploy after syncing:

nexus-dl deploy ~/mods/bg3

Downloading puts files in a staging area. Deploying links them into the game directory.

Something else went wrong

Check the Issues page on GitHub to see if someone has reported the same problem, or open a new issue with the error message you're seeing.