Using Mods

Modding your game, for users

Troubleshooting

Summary

Published: Jun 15, 2023 by mana vortex Last documented update: September 19 2025 by icxrus, minnie and dirtyVans

This page will give you a brief introduction of how mods work and how to install them by hand.

Wait, this is not what I want!

How to install mods

How do I mod?

You mod Cyberpunk 2077 by adding files to your game directory. The game natively supports modding, and the core mods will take care of everything else.

You can install mods by using Vortex/Mod Organizer 2, or by hand.

Regardless of your past experiences, the Nexus Mod Manager Vortex works reliably and well for modding Cyberpunk.

What are dependencies / requirements?

For more detailed information, see Users: troubleshooting requirements.

The core mods

To learn more about this, check Core Mods explained.

Cyberpunk 2077 offers limited out-of-the-box support via REDmod. To allow greater freedom, a number of core mods have been created — without them, we couldn't add items, influence the weather, or have flying cars.

Overview of mod folders

TL;DR: you can ignore this unless you want to understand how things work, or want to install mods manually.

This list is supposed to give you an overview of which files go where. It is not a bucket list of things you have to install.

To learn more about the individual frameworks, check Core Mods explained

Directory
explanation

\mods

REDmod directory: contains .archive mods (in subfolders). Contains only a .stub file if empty.

\archive\pc\mod

Default mod directory: contains .archive mods and .xl files in legacy (non-REDmod) format. Most of your mods should be here.

\bin\x64\plugins

Plugins like Cyber Engine Tweaks and RadioExt

\r6\scripts

Redscript mods (not the same as REDmod)

\r6\tweaks

red4ext tweaks

\archive\pc\patch

Mod directory from before 1.3. Use \archive\pc\mod instead.

- archive
  - pc
    - mod          << .archive files from non-REDmods go here
- bin
  - x64
    - plugins      << Cyber Engine Tweaks goes here
- mods             << REDmods go here
- r6               << redscript folder
  - scripts        << redscript mods (not the same as REDmod)
  - tweaks         << RED4ext tweaks (TweakXL / ArchiveXL)
- tools            << REDmod DLC lives here — only needed for making mods.

Installing and activating REDmod

If REDmod is not installed and activated, your mods in /mods will not load.

REDmod never took off and most people stick to the legacy format. If your /mods folder is empty, you don't need this. For more information, see What's the difference? below.

Loading a mod as REDmod means that Cyberpunk will precompile it to optimize load times — integrating it into the game's other files by adding it to the files under r6/cache.

By contrast, vanilla mods (from /archive/pc/mod) will be loaded individually and might add to your load times.

  • For instructions on how to install, see here.

  • For documentation on the Vortex installation toggle, see here.

  • For instructions on how to activate it, see here for GOG and here for Steam and Epic.

REDmods are installed in Cyberpunk 2077\mods, where every mod has a subfolder with an info.json.

Installing Mods

You can install mods via mod manager (Vortex, mo2) or manually. There are upsides and downsides to each — however, for beginners, we recommend using Vortex.

Manual install

"Manual install" is a rather glorified term for "extracting the downloaded archive into your game directory". However, you have to make sure that the right files end up in the right folders.

You can inspect the file structure by simply opening the downloaded file, or by using this feature on Nexus (unless a mod author has disabled it):

The file structure is different for REDmods and non-REDmods. Mod authors usually tell you which file is which, though. To find out what that means, read on.

Mod format: REDmod or vanilla?

Here is how you can tell the two apart:

REDmod
Vanilla mod (packed correctly)

is in a folder named after the mod

may be in an extra folder if packed incorrectly

has an info.json

does not have an info.json

contains a folder with any of

- archives

- tweaks

contains any of the folders - archive - bin - r6 with files nested under them

Is packed with one level of nesting (info.json is in top level folder)

Has multiple levels of nesting

Manual install instructions: Extract the folder ModName into Cyberpunk 2077/mods

Manual install instructions: The folders archive, bin, r6 from the download must merge with the same folders in your game directory (do not put the bin in the bin).

What's the difference?

All REDmods mods will be preloaded by redMod.exe before the game starts up. After a short delay, the mods will then be loaded as if they were part of the game itself — you're saving the startup delay on every savegame load.

On top of this, Vortex will let you define load order for REDmods. To support compatibility, it offers you automatic conversion.

That sounds awesome, why isn't it everywhere?!

Compatibility issues

REDmod was CDPR's attempt to standardize mod loading, but there were various compatibility issues with it, and it never quite took off. As of today (April 2024), the project is pretty much dead in the water.

Load order

REDmods are loaded after everything else, so that format is simply not an option for e.g. body mods.

Vortex autoconvert

In theory, Vortex can automatically convert legacy mods to REDmod. In practice, that didn't help with any of the compatibility issues mentioned before, and caused some of them.

Fixing broken mod file paths

Sometimes mod makers create strange pathings for their mods, or delete the paths all together, even when Wolvenkit creates those paths for them. This can cause issues especially when installing mods with a mod manager, as the mod manager doesn't know where this mod is supposed to go.

You'll usually see a few types of mismatches of pathing:

Scenario 1: Files without any folders
Scenario 2: Files inside non-game sub folders
Scenario 3: Unnecessary first subfolder

All of these can cause a mod manager to get mixed up, or for you to install it wrong when installing manually, so let's go through fixing these!

You can do these fixes in the file explorer or through Vortex/MO2 if you're using them.

To find out how to install the mod properly, you have to read the mod's install instructions. If that isn't clear enough, the following might help you.

Manually fixing the folder paths

  1. Extract the .zip/.rar/.7z archive to your Downloads folder (or whatever folder you're working in). You might get an extra unnecessary folder depending on what path you extracted the packaged archive to. If you want it to extract straight into the Downloads folder, remove the extra folder at the end of the path so it looks something like this:

In the case of Scenario 3, you can just move the folders out of the first unnecessary folder and continue from step 8 or 9.

  1. You should now have all of the mod files inside your Downloads folder. Locate the files you want to move and check their file extensions. If you don't have file extensions turned on, you can check this part of the file to know what file it is:

  1. Now that we have found our files, we need to place it into the correct file path by creating that file path. This is an .archive file so it needs to go into archive/pc/mod/ file path. If you aren't sure where your file should go, check out Mod folders by file extension.

  2. Create a folder by right clicking. Name it archive.

  3. Enter the archive folder you just created by double clicking on it. Now repeat step 4. but this time name it pc.

  4. Enter the pc folder, and repeat step 4. one last time, this time naming the folder mod. Repeat this process for the correct folder paths for other file types if you have any. For our .archive you should have a folder path like this now:

  1. Now go back into the Downloads folder (or any subfolder that holds the files we need to move). Select the files and press CTRL + X to cut the files, then navigate back into your corrected folder path, and press CTRL + V to paste the file there. You should end up with something like this:

  1. If you're manually installing, you can now copy paste the archive folder into the Cyberpunk 2077 folder where your game is installed, it will automatically merge with the existing folders.

  2. If you're using a mod manager, right click the archive folder and turn it into a .zip/.rar/.7z. If you're just using Windows' own zipping system, the option might be hidden under Send to -> Compressed (zipped) folder.

  1. Name the newly created .zip to whatever you want, however it is recommended you name it something identifying, like the original mod name, so you can find the mod on Nexus again as adding the mod this way to your mod manager will not preserve links.

  2. You can now add it to your mod manager. For Vortex, drag the .zip to the bottom of the downloads page and drop it there.


Fixing the folder paths inside Vortex

Vortex can be incredibly useful, but it cannot magically fix badly packaged mods on its own. Sometimes, it requires your intervention. When you press the shiny "Deploy Mods" button, it doesn't have a particularly complex way of figuring out which files go where. In essence, it just dumps the folders into the game directory, and mod files end up wherever they end up. Usually, if they're packaged correctly, the mod files will end up exactly where they need to be. Sometimes, there will be unnecessary subfolders that mean the mod files don't end up where they should be.

This is a lot of words to say that some mods are just packaged wrong. Don't worry, we'll fix it!

Well, what do I do then?

Always check the file contents before downloading a mod! Vortex cannot guess that a mod isn't packaged correctly. Sometimes there is a popup for unexpected installation paths, but this doesn't mean a mod is packaged badly. Unfortunately, mods packaged incorrectly will not be flagged by Vortex as wrong.

Go to a mod's "FILES" tab on Nexus, then click "Preview File Contents".

Folder structure should look similar to this!

Usually mods that make you choose between different files need manual adjustments.

If the mod you've downloaded looks like the picture on the left. Great! You don't need to do anything. Enjoy your game! If not, keep reading... we've got work to do!

Adjusting folder structure in Vortex - Step by Step:

  1. Press "Mod Manager Download" as you normally would.

  2. Navigate to "Never Installed" in Vortex (on the "Mods" tab). You should see the mod you just downloaded here.

  3. Right click on the mod name

  4. Click "Install"

    We don't want to enable this mod yet! It will make it more difficult in the future if we do!
  5. You should get a popup that says "You have reached the fallback installer!". Click "Yes, Install to staging anyway".

  6. You should then get another pop-up that says "Mod installed but may need manual adjustment!". Click "Understood!" You should read this pop-up! It explains where the files are expected to go and why!

    Just read the dang pop-up, I promise!
  7. The mod should now be under "Disabled." Right click the mod name again to bring up the menu.

  8. Click "Open in File Manager".

  9. To make life easier for ourself, we'll start setting up the proper folder structure the first folder it takes us to. That way, we can just cut and paste what we need into the proper place!

  10. Make sure you follow this folder structure exactly. We need to create a folder named archive. Click into the archive folder and create one called pc. Click into pc and create a folder called mod.

  11. We're going to have to use some brainpower here and click through the folders until we find the exact files we want. In this example, I want to use the "COOL VERSION", so I would click through the folders until I find the "COOL VERSION" files.

  12. Select the files you need and cut them!

  13. Go to the end of the folders we made in step 10 and paste them!

  14. Repeat this process for any other folders that contains files you need to make sure your mod works. Don't worry, there's a table at the bottom of this page (here!) which shows the paths you need to create for each file type!

  15. Now to deal with the folders that you did not make. Select them and press delete!

  16. Guess what! We can finally go back into Vortex and enable that mod!

    Yippee!!! You did it!
  17. Now you can get back to your regularly scheduled mod downloading session. Hooray!

Fixing the folder paths inside MO2

First and foremost I recommend to set up your MO2 Installer to default to the manual installer instead of using the Simple Installer plugin. MO2 already checks for a correct path and will warn you if the mod you are trying to install deviates from the expected structure, but I find removing the Simple Installer plugin helpful for both new users as well as MO2 veterans regardless. It might seem overkill at first but is a valuable tool to make sure the user checks for a working file structure so the mod ends up where it's supposed to be. If you are unsure where files should go refer back to the "Overview of mod folders" section of this guide. To get started open your MO2 settings and click the plugins tab.

In the left pane scroll down to the Installer section and make sure Simple Installer is disabled.

Now you can go to Nexus and download mods using the Download with Manager button as per usual. Often times mod authors set a correct file structure but due to how packaging works they end up with an additional folder that MO2 doesn't know how to handle. In these instances you have to manually change the Cyberpunk 2077 directory in the installer. I will explain how you do that in Example #1 below. Further down in Example #2 I will explain how to create new folders from scratch in case they are missing completely or only partially correct.

If you make a mistake you can cancel out of the installation process during any given step and start again! Even if you somehow falsely install something you can right click your mod in MO2 and select the "reinstall" option to restart the manual adjustment.

Example #1: Adjusting the Cyberpunk 2077 directory

  1. MO2 is unhappy because it doesn't recognize a correct file path, due to an additional folder inside the mod.

  2. This is easily fixed by making MO2 recognise the additional folder as the Cyberpunk 2077 directory itself by right clicking the folder and selecting "Set as <cyberpunk 2077> directory".

  3. Now that we are left with the .archive file going into Cyberpunk 2077/archive/pc/mod/ MO2 is happy and gives us the green light for the installation and you can finalise the process by clicking OK.

Example #2: Creating your own folders

  1. MO2 is unhappy because it doesn't recognize a correct file path, due to the lack of any folders guiding the .archive to the correct location.

  2. Right click the Cyberpunk 2077 directory and select "Create directory". Name the new folder "archive" and press ok.

  1. Repeat this process two more times by creating a new directory named "pc" inside the archive folder and another named "mod" inside the pc folder. The result should look like this.

  2. Now all that is left to do is to drag the .archive file into the mod folder. MO2 should then give you the green light for installation and you can finalise the process by clicking OK to install your mod.

For bigger and more complicated mods - for example those that come with multiple .archive files to select from - you can also utilize the checkmarks to enable or disable files and folders as needed, or drag multiple files to the location they need to be in. Often times I end up creating my own structure as above and then drag the files I want there while simply disabling the files I do not need. MO2 will ignore and ultimately not install them.

You can now enable your mods like any other. Happy gaming!

Mod folders by file extension

As a rule of thumb, here's which files go where (unless the mod's instructions tell you otherwise):

File type
Folder path

.archive

/archive/pc/mod/

.xl .archive.xl

/archive/pc/mod/

.reds

/r6/scripts/

.tweak .yaml

/r6/tweaks/

.lua

a subfolder of /bin/x64/plugins/cyber_engine_tweaks/

.ini

engine/config/platform/pc

.script

part of a REDmod, can't be installed standalone

Troubleshooting

If you have problems with Vortex, check the corresponding section of the guide.

For everything else, this wiki has a dedicated troubleshooting page with step-by-step instructions for pretty much every common problem. If that doesn't cut it, you're welcome to find us on Discord in the #mod-troubleshooting channel (but your first answer will be a link to that guide).

Last updated