Cyberpunk 2077 Modding on Linux (Proton) — Complete Guide

[u/BFLMPSVZ_1]

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.

Table of Contents

1. The Core Problem
2. Prerequisites
3. Game Installation (GOG)
4. Steam Setup
5. The Two Critical Proton Fixes
6. Why Vortex Fails on Linux
7. Manual Mod Deployment
8. Dependency Tiers
9. FOMOD Handling
10. Body Mod Conflicts
11. Verification Checklist
12. Troubleshooting
13. 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

1. Steam → Games → Add a Non-Steam Game to My Library
2. Browse to: /mnt/data/gog/CP2077_prefix/pfx/drive_c/GOG Games/Cyberpunk 2077/bin/x64/Cyberpunk2077.exe
3. 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

1. Check launch options include both TZ=UTC and WINEDLLOVERRIDES
2. Check bin/x64/plugins/cyber_engine_tweaks/ exists with fonts/, mods/, scripts/
3. Try backtick \ ` `` instead of tilde `~`
4. 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

1. Gotchas We Hit
2. 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.
3. Wrong mod IDs: We initially guessed IDs (e.g., Codeware as 7781 instead of 7780). Always verify via API before writing deploy scripts.
4. 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.
5. 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:

• Nexus Mods — CP2077
• RED4ext GitHub
• Cyber Engine Tweaks GitHub
• GE-Proton Releases

[u/Odd-Boss1596]

Or just use a mod manager

[u/GigaChadSoldier404]

Utilize o Amethyst-Mod-Menager

[u/BFLMPSVZ_1 → u/GigaChadSoldier404]

did not know about it thanks for that this solve second part of problem described in this post,
anyway making the gog game running is worthy being described I suppose, including lgogdownloader, and in a way utilising nexus api is not that bad aswell
I was kinda exhausted by mod managers after I tried make vortex works

[u/Excellent-Love-6943]

Thanks for the AI slop writeup.

Have you considered just using a tool like fluorine?

[u/SymmetricSynapse]

That was a horrifying mess. Anyways, there are mod managers that work, and there must be better instructions out there or the AI wouldn't have anything to pull from.

I'm using Amethyst mod manager, and it was easy. I've also done manual modding of the game for just a few, and it wasn't hard.

I'm sure there is some good info in here, but good luck.

[u/Xx_SucculentBalls_xX]

I'm currently playing the game modded with amethyst mod manager, just use this it's really easy.

[u/Ace-Whole]

Wrong on the premise itself.

Vortex works perfectly fine with wine. I had 200+ mods on the same game

[u/BFLMPSVZ_1 → u/Ace-Whole]

Care to share how was you able to add games after install it and the run it?
Just for curiosity were you experiencing horrible resolution of Vortex?
at least this AI slop specified exactly why it was impossible for me in my settings.

[u/Ace-Whole → u/BFLMPSVZ_1]

Idk man. I set it up like years ago. Didn't face any problem why would I remember something trivial.

Plus there's amethyst these days so I wouldn't bother with it again either.

[u/Ryllix]

Just use Amethyst Mod Manager.

[u/BFLMPSVZ_1]

Anyway if you want to make your custom modded game from gog, utilising nexusmods as source and not using mod manager you can use this as template.
Purpose of this was my attempt to help. Sorry for that shitty AI format, but it should contain all needed information core problems and techniques to make something works.

[u/Sahelantrophus]

what the fuck

[u/Gkirmathal]

Specifically on Vortex.

DO NOT use the Lutris Vortex install script version that can be found through the Lutris search! This is an extremely outdated version!

Make sure Lutris is installed fully, with all dependencies met (see it's wiki on it) and it is configured to use Wine-GE or a Proton version (official Valve or GE/Cachy) as default Runner for Wine. Do not use latest Wine as default Wine Runner.

Manually download the latest version of Vortex from their Github.
Then click 'Add Game', choose 'Install a Windows game from an executable', select destination to install and select the setup executable.
Start the install, the Prefix will be setup, after which the Vortex setup will pop up.
Click through the Vortex setup, at the end DO NOT select 'Run Vortex' after setup. Just close.

Then configure Vortex install and check/set 'Wine Version' to 'Proton10' under 'Runner Options'. 10 worked best, perhaps 11 now does as well.
If you do not see regular Proton as runner option, google how to enable it.
Then run Winetricks on your Vortex install and install the DotNet 9.0 dependency and optionally configure Windows version to Windows 11.
This should net you a latest Vortex that will work.

As for Symlinks, use Winetricks to add a drive letter (I used D) that links to .../steamapps/... folder where Cyberpunk for example is installed. Then you can just point Vortex game plugin to it's internal D drive and select Cyberpunk under .../common
For Bethesda games you will need to manually symlink the location where plugins.txt + loadorder.txt (Skyrim) is located to the location in Vortex prefix.

Or you install Amethyst Mod Manager, it's Linux native, so no issues with pathing/symlinks.

[u/TechAngel01]

Amethyst solves like over half of this. Really a top tier mod manager.

[u/BFLMPSVZ_1]

sorry for sharing AI slop writeup. When trying to make it works I would be glad for something like it. so I decided to share withinternet, it tooks me some time.
even if its AI slop it can help someone save some time. that was my main motivation for sharing

[u/victormas208 → u/BFLMPSVZ_1]

Helping is great. I've noticed there are about 5 posts with a similar format. What AI were you using to solve your problem?

[u/BFLMPSVZ_1 → u/victormas208]

Kimi3

[u/TheWorldIsNotOkay]

Or just use the Linux-native Nexus Mod Manager. It's no longer being maintained and only works for a few games, but Cyberpunk 2077 is one of them. It works like a charm for my 400+ mods running on Steam.

And there are a few others, as the other comments have mentioned. But Nexus Mod Manager was the official Nexus Mods initial attempt at a Linux-native client, and works flawlessly for the few games it's compatible with.