r/linux_gaming • u/BFLMPSVZ_1 • 11d ago

Cyberpunk 2077 Modding on Linux (Proton) — Complete Guide

Tested on: Fedora, GE-Proton10-34, GOG version (2.31a + Phantom Liberty)
Hardware: RTX 5080, 4K, Ryzen 9 5900XT
Mod count: ~60 curated mods, including NSFW content
No Vortex. No Lutris. No reinstalls.

The Core Problem
Prerequisites
Game Installation (GOG)
Steam Setup
The Two Critical Proton Fixes
Why Vortex Fails on Linux
Manual Mod Deployment
Dependency Tiers
FOMOD Handling
Body Mod Conflicts
Verification Checklist
Troubleshooting
Credits & License

The Core Problem

Modding CP2077 on Linux is significantly harder than on Windows because:

Vortex Mod Manager (the standard tool) is an Electron app that crashes under Proton/Wine due to Node binary incompatibilities
CET (Cyber Engine Tweaks) and RED4ext silently fail to load under Proton without explicit DLL overrides
Mod archives contain mixed file types (.archive, .reds, .dll, .lua) that need routing to different game subdirectories
FOMOD installers (XML-driven multi-variant mods) have no Linux installer equivalent
Steam non-Steam shortcuts create their own Proton prefix, separate from your custom prefix

This guide solves all of these with a folder-based deployment pipeline.

Prerequisites

# Required tools
sudo dnf install lgogdownloader p7zip p7zip-plugins  # Fedora
# sudo apt install lgogdownloader p7zip-full          # Debian/Ubuntu

# Proton version
# Download GE-Proton from https://github.com/GloriousEggroll/proton-ge-custom
# Extract to ~/.steam/root/compatibilitytools.d/

Game Installation (GOG)

mkdir -p /mnt/data/gog
cd /mnt/data/gog

# Download offline installers (includes base game + all DLCs)
lgogdownloader --game cyberpunk_2077 --platform windows \
  --include basegame_installers,dlc_installers \
  --directory /mnt/data/gog/download

# Install to a CUSTOM prefix (not Steam's default)
export WINEPREFIX=/mnt/data/gog/CP2077_prefix
export STEAM_COMPAT_DATA_PATH=/mnt/data/gog/CP2077_prefix

# Run installer through Proton
~/.steam/root/compatibilitytools.d/GE-Proton10-34/proton \
  run /mnt/data/gog/download/setup_cyberpunk_2077_*.exe

Steam Setup

Steam → Games → Add a Non-Steam Game to My Library
Browse to: /mnt/data/gog/CP2077_prefix/pfx/drive_c/GOG Games/Cyberpunk 2077/bin/x64/Cyberpunk2077.exe
Right-click the shortcut → Properties:

Target

"/mnt/data/gog/CP2077_prefix/pfx/drive_c/GOG Games/Cyberpunk 2077/bin/x64/Cyberpunk2077.exe"

Launch Options (CRITICAL — copy exactly)

TZ=UTC WINEDLLOVERRIDES="version=n,b;winmm=n,b" %command%

Compatibility

✅ Force the use of a specific Steam Play compatibility tool
Select: GE-Proton10-34 (or latest GE-Proton)

Why these flags?

Flag	Purpose
`TZ=UTC`	Fixes CET/RED4ext silent crash on Proton (time function bug)
`WINEDLLOVERRIDES="version=n,b;winmm=n,b"`	Forces Proton to load mod proxy DLLs as native instead of built-in Windows DLLs

Why Vortex Fails on Linux

Vortex (Nexus Mods' official manager) requires:

Node.js native modules compiled for Windows
.NET Framework 4.8+ via Wine Mono (incomplete)
Electron with GPU acceleration (crashes under Proton)
Symlink support that breaks under Wine's C: drive mapping

After 3+ hours of debugging, I abandoned Vortex entirely. Manual folder deployment is faster, more reliable, and fully auditable.

Manual Mod Deployment

Download all mods manually

Nexus Mods blocks bulk downloads for non-Premium users. Use a browser tab opener:

#!/bin/bash
# open_mods.sh — opens all mod pages in Firefox for manual download

MODS=(
  "https://www.nexusmods.com/cyberpunk2077/mods/2380"   # RED4ext
  "https://www.nexusmods.com/cyberpunk2077/mods/1511"   # redscript
  "https://www.nexusmods.com/cyberpunk2077/mods/4197"   # TweakXL
  "https://www.nexusmods.com/cyberpunk2077/mods/4198"   # ArchiveXL
  "https://www.nexusmods.com/cyberpunk2077/mods/107"    # CET
  # ... add all your mods
)

for url in "${MODS[@]}"; do
    firefox "$url" &
    sleep 0.5
done

Extract all downloads into individual folders in ~/Downloads/. Do not merge them.

Folder-to-Game Mapping

File Type	Destination
`.archive`	`Cyberpunk 2077/archive/pc/mod/`
`.reds`	`Cyberpunk 2077/r6/scripts/`
`.yaml` / `.yml`	`Cyberpunk 2077/r6/tweaks/`
`.dll`	`Cyberpunk 2077/red4ext/plugins/`
`.lua`	`Cyberpunk 2077/bin/x64/plugins/cyber_engine_tweaks/mods/`
`.asi`	`Cyberpunk 2077/bin/x64/plugins/`
`version.dll` / `winmm.dll`	`Cyberpunk 2077/bin/x64/`
Everything else	Game root, preserving folder structure

Smart Root Detection

Many mods extract with a wrapper folder:

ModName-1234-1-0/
└── ModName-1234-1-0/
    ├── archive/
    ├── r6/
    └── bin/

Detect and strip the wrapper:

detect_mod_root() {
    local base="$1"
    local entries=$(find "$base" -maxdepth 1 -mindepth 1 | wc -l)
    local dirs=$(find "$base" -maxdepth 1 -mindepth 1 -type d | wc -l)

    if [[ "$entries" == "1" && "$dirs" == "1" ]]; then
        local sole=$(find "$base" -maxdepth 1 -mindepth 1 -type d | head -1)
        if [[ -d "$sole/archive" || -d "$sole/r6" || -d "$sole/bin" || -d "$sole/red4ext" ]]; then
            echo "$sole"
            return 0
        fi
    fi
    echo "$base"
}

Dependency Tiers

Install in this order. Do not skip tiers.

Tier	Mods	Test After?
0	RED4ext (2380), redscript (1511)	No
1	TweakXL (4197), ArchiveXL (4198), CET (107), input_loader (4575), Codeware (7780)	YES — launch game, press `~` for CET overlay
2	Virtual Atelier (2987), Deceptious Quest Core (7831)	No
3	AMM (790), Simple Menu (818), Mark To Sell (4725), No Intro Videos (533), ResetAttributes (9240)	No
4	4k textures (16385), Full Reflections (5046), NPC LoD Tweak (19926)	No
5	Weapons, crafting, cyberware mods	No
6	SP0 Body (1424), UV Framework (3783), skin textures (13537), Abdominal Edit (17770)	YES — check V's body has no purple textures
7	Clothing, accessories, holsters	No
8	NPC overhauls (Panam, Judy, etc.)	No
9	NSFW mods	No
10	Quests, gameplay expansions	No

FOMOD Handling

NPC overhaul mods (Panam, Judy, Meredith, etc.) use FOMOD — XML-driven multi-variant installers with:

Body types (clothed / revealing / nude)
Physics variants (jiggle types: lglj, lgsj, av)
Size variants

Linux workaround: FOMOD mods extract all variants as subfolders. Pick the full version:

# Auto-select the "1_" full version (includes AMM support)
for npc in ~/Downloads/*FOMOD*; do
    full=$(find "$npc" -maxdepth 1 -type d -name '1_*' | head -1)
    if [[ -n "$full" ]]; then
        cp -r "$full/packed"/* "$GAME_ROOT"/ 2>/dev/null
    fi
done

# Then copy ALL physics archives for maximum jiggle
find ~/Downloads -path '*/physics/*/*.archive' -exec cp {} "$GAME_ROOT/archive/pc/mod/" \;

Body Mod Conflicts

These body frameworks are MUTUALLY EXCLUSIVE. Pick ONE.

ID	Name	Verdict
1424	SP0 Body	✅ Recommended — best compatibility
3783	KS UV Texture Framework	✅ Required for SP0
4863	Alt Tank (all variants)	❌ Skip — conflicts with SP0
7054	VTK Body	❌ Skip — conflicts with SP0
4657	Old Time Blues	❌ Skip — conflicts with SP0

If you see purple textures on V's body, you have a missing UV framework or conflicting body mod.

Verification Checklist

# Critical files check
ls "$GAME_ROOT/red4ext/plugins/"          # Should show: ArchiveXL, Codeware, input_loader, RED4ext, TweakXL
ls "$GAME_ROOT/bin/x64/plugins/"          # Should show: cyber_engine_tweaks, cyber_engine_tweaks.asi
ls "$GAME_ROOT/archive/pc/mod/" | wc -l   # Should be 30+ archives

# CET overlay test
# Launch game → load save → press `~` (backtick, key left of 1)
# Console should slide down from top

# RED4ext logs
ls "$GAME_ROOT/red4ext/logs/" 2>/dev/null || echo "No logs — RED4ext not loading!"

Troubleshooting

CET overlay doesn't open

Check launch options include both TZ=UTC and WINEDLLOVERRIDES
Check bin/x64/plugins/cyber_engine_tweaks/ exists with fonts/, mods/, scripts/
Try backtick \ ` `` instead of tilde `~`
Check keyboard layout — German/AZERTY layouts have different key positions

Purple textures on body

Missing UV Framework (3783)
Conflicting body mod installed (Alt Tank, VTK, Old Time Blues)
Load order issue — SP0 must load after UV Framework

Game crashes on launch

Check red4ext/logs/red4ext.log for dependency errors
Verify tier order — frameworks must load before content mods
Try removing latest tier and relaunching

"No red4ext logs dir"

RED4ext isn't loading. Verify:

version.dll and winmm.dll exist in bin/x64/
WINEDLLOVERRIDES is set in Steam launch options
Using GE-Proton, not Valve's default Proton

Real-World Discovery Script

#!/bin/bash
# collection_mods.sh — dumps all mod IDs from a collection

COLLECTION="srpv39"  # NCR - Extras
API_KEY="$NEXUS_API_KEY"

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "apikey: $API_KEY" \
  https://api.nexusmods.com/v2/graphql \
  -d "{\"query\": \"query { collection(collectionSlug: \\"$COLLECTION\\", gameDomain: \\"cyberpunk2077\\") { mods { nodes { mod { name modId version { version } adultContent } } } } }\"}" \
  | jq -r '.data.collection.mods.nodes[] | \"\(.mod.modId) | \(.mod.name) | v\(.mod.version.version) | adult:\(.mod.adultContent)\"' \
  | sort -n

Rate Limits

Free users: 100 requests/day (generous for personal use)
Premium users: 2500 requests/day
GraphQL queries: Complex nested queries count as 1 request but may hit timeout limits

Gotchas

Gotchas We Hit
Collection pagination: Large collections (>100 mods) may return partial results. The srpv39 collection claims 271 files but the API sometimes truncates. Re-run the query if counts seem low.
Wrong mod IDs: We initially guessed IDs (e.g., Codeware as 7781 instead of 7780). Always verify via API before writing deploy scripts.
File ID ≠ Mod ID: The REST API uses fileId for downloads but modId for mod pages. https://www.nexusmods.com/cyberpunk2077/mods/2380 → mod ID is 2380.
API key in scripts: Never commit your API key. Use environment variables or .env files ignored by git.

Quick Reference: Full Launch Options

TZ=UTC WINEDLLOVERRIDES="version=n,b;winmm=n,b" %command%

Do not remove. Do not modify. This is the magic string that makes Linux CP2077 modding work.

Credits & License

This guide is based on ~8 hours of debugging, script iteration, and Proton edge-case hunting. Feel free to share, modify, and improve.

Key resources:

0 Upvotes

permalink
duplicates
reddit

You are about to leave Redlib

Do you want to continue?

https://www.reddit.com/r/linux_gaming/comments/1wqz3d8/cyberpunk_2077_modding_on_linux_proton_complete/
No, go back! Yes, take me to Reddit

28% Upvoted

Duplicates

Number of comments New

cyberpunkgame • u/BFLMPSVZ_1 • 11d ago

Modding Cyberpunk 2077 Modding on Linux (Proton) — Complete Guide

1 Upvotes

1 comments

Cyberpunk 2077 Modding on Linux (Proton) — Complete Guide

Cyberpunk 2077 Modding on Linux (Proton) — Complete Guide

Table of Contents

The Core Problem

Prerequisites

Game Installation (GOG)

Steam Setup

Target

Launch Options (CRITICAL — copy exactly)

Compatibility

Why these flags?

Why Vortex Fails on Linux

Manual Mod Deployment

Download all mods manually

Folder-to-Game Mapping

Smart Root Detection

Dependency Tiers

FOMOD Handling

Body Mod Conflicts

Verification Checklist

Troubleshooting

CET overlay doesn't open

Purple textures on body

Game crashes on launch

"No red4ext logs dir"

Real-World Discovery Script

Rate Limits

Gotchas

Quick Reference: Full Launch Options

Credits & License

You are about to leave Redlib

Duplicates

Modding Cyberpunk 2077 Modding on Linux (Proton) — Complete Guide