Installing plugins on a Rust server (Oxide and Carbon)

A Rust plugin is a single file with the .cs extension. You upload it to the right folder and the framework loads it by itself, without restarting the server. This guide shows where to find plugins, how to install, configure, translate, update and remove them, and what to do when they don't load.

How plugins work#

• A plugin is C# source code. The framework watches the plugin folder and compiles and loads any new or changed file by itself. You don't need to restart the server for that.
• When it loads for the first time, a plugin usually creates a configuration file (JSON) with the same name as the plugin, and possibly data (player homes, cooldowns…) and language files.
• Oxide and Carbon use the same plugins. Only the folder names and the command prefix differ.

Where to find plugins#

• umod.org (opens in a new window) – the Oxide project's site with thousands of free plugins (they also work on Carbon). Filter the list by the game Rust.
• Paid marketplaces and authors' websites – larger plugins (events, economies, maps) are sold there. Only buy from the original seller.

Before installing any plugin, check:

• The date of the last update. A plugin that hasn't been updated after a major Rust update may not compile.
• The description of permissions and commands on the plugin page. You can't set it up without them.
• Dependencies. Some plugins need another plugin (for example ImageLibrary for images in menus).

Installing a plugin#

Check that the plugin is running by listing plugins in the console:

Folder structure#

The difference between configuration and data: you edit the configuration (how the plugin should behave), while the plugin manages its data itself (what it remembers about players). Don't edit data by hand unless you know exactly what you're doing.

Editing a plugin's configuration#

The configuration is named after the plugin: the Kits.cs plugin keeps its settings in oxide/config/Kits.json (in Carbon, carbon/configs/Kits.json). If the file didn't appear after the plugin loaded, the plugin either has nothing to configure or didn't load (check the logs).

A safe procedure that keeps the plugin from overwriting your changes:

Why unload first: some plugins save their current configuration when they unload. If you edited the file while the plugin was running and then only ran reload, the plugin could overwrite your changes with the old values. For plugins that don't do this, you can simply save the file and run oxide.reload Kits (c.reload Kits).

JSON rules#

{
  "Enabled": true,
  "Cooldown (seconds)": 600,
  "Welcome message": "Welcome to the server!",
  "Allowed items": [
    "rock",
    "torch"
  ],
  "Colors": {
    "Admin": "#ff5555",
    "Player": "#55aaff"
  }
}

• Keys and text always in double quotes ("Enabled"). JSON doesn't know single quotes.
• A comma after every item except the last one in a given block. An extra comma before } or ] is the most common mistake.
• true and false in lowercase and without quotes. "true" in quotes is text, not “on”.
• Numbers without quotes: 600; decimals with a dot: 1.5.
• A list goes in square brackets [ ], a group of settings in curly braces { }.
• JSON doesn't support comments. Don't change key names, only the values after the colon.

Before uploading, check the file with a JSON validator (an editor such as Visual Studio Code does this and underlines the error). If you break the configuration completely, delete it and reload the plugin – it will create a default file.

Translating plugins into other languages#

The texts a plugin sends to players are in the oxide/lang/<language>/<Plugin>.json files (Carbon: carbon/lang/…). The plugin picks the language based on the language the player has set in the game. If there's no file for that language, it uses the server language and finally English.

You have two options:

• All players in your language: translate the English file oxide/lang/en/<Plugin>.json directly. Everyone who doesn't have their own language version will see it.
• Your language only for players whose game uses it: create a folder named after the language code (for example oxide/lang/cs for Czech), copy the English file into it and translate it. If players with the game set to that language still see English texts, use the first option.

Translate only the texts after the colon. Leave placeholders such as {0} or {player} unchanged; the plugin fills in the values. You can keep or adjust color tags like <color=#ff5555>…</color>. When a plugin is updated, the framework only adds new texts to the language file, so your translations stay.

You set the server's default language with the oxide.lang command in the server console, for example oxide.lang cs for Czech (in Carbon, c.lang cs).

Dependencies and extensions#

A dependency on another plugin shows up in the plugin's description or as an error in the console (see Troubleshooting). The fix: install the required plugin too, the same way, into the plugin folder. A typical example is ImageLibrary, which downloads and stores menu images for other plugins.

An extension is a .dll file, not .cs. They're used, for example, by custom maps from the RustEdit editor or for Discord integration. Extensions are only loaded when the server starts:

• Oxide: upload the .dll to RustDedicated_Data/Managed and restart the server.
• Carbon: upload the .dll to carbon/extensions and restart the server.

A caveat for Oxide: a game update overwrites files in the RustDedicated_Data/Managed folder. Your own Oxide.Ext.*.dll extensions usually survive, but if you ever delete the Managed folder (for example when repairing a broken installation), they're gone. Keep backups of them outside the server as well.

Plugin management commands#

Replace Kits with the plugin name, i.e. the file name without .cs. Enter the commands in the server console, over RCON, or as an admin in the in-game F1 console.

Updating a plugin#

1. Read the changelog on the plugin page. Major versions (for example 3.x to 4.x) can change the configuration.
2. Back up the plugin's configuration and data.
3. Upload the new .cs file over the old one (same name).
4. The framework detects the change and reloads the plugin by itself. The console shows the plugin unloading and loading again.

Configuration and data stay. Most plugins add new settings introduced in the new version to the configuration by themselves.

Removing a plugin#

1. Unload the plugin: oxide.unload Kits (Carbon: c.unload Kits).
2. Delete the Kits.cs file from the plugin folder.
3. If you don't want the plugin in the future either, also delete its configuration, data and language files (files and folders named after the plugin in config/configs, data and lang).

The removed plugin's permissions stay assigned to groups. That does no harm, but it doesn't help keep things tidy. In Carbon, the c.cleanup orphans command cleans them up.

Security#

• A plugin can do anything on the server: read and delete files, run console commands, send data to the internet. Only install plugins you trust.
• Never install “leaked” (illegally distributed) paid plugins. They're often modified to give an attacker admin rights or access to the server.
• A plugin is readable source code. If you find obfuscated code or downloads from unknown addresses in it, don't use it.
• Never paste your RCON password into websites and tools you don't know.

Troubleshooting#

The console shows Error while compiling Kits:#

The plugin couldn't be compiled. After the colon (Oxide gives the plugin name without .cs) comes a list of errors with line numbers (for example error CS0246). oxide.plugins shows the same reason for a plugin that didn't load. In Carbon, a similar error starts with Failed compiling 'Kits.cs':. The most common causes:

• The plugin is outdated for the current version of Rust or the framework. Download the latest version of the plugin, or wait until the author releases one after the Rust update.
• The file was downloaded corrupted (for example a web page instead of code). Open it in an editor: it has to contain C# code (lines like using … and namespace Oxide.Plugins), not HTML. Download it again.

The console shows … plugin requires missing dependency: …#

The plugin needs another plugin that isn't on the server. The name of the missing plugin is at the end of the message. Install it and the plugin then loads by itself (or load it with oxide.load). In Carbon, the message reads Couldn't find required plugin '…' for '…', retrying...

The plugin didn't show up at all, the console is silent#

• The file is in a subfolder (for example oxide/plugins/Kits/Kits.cs). It has to be directly in the plugins folder.
• The file has a different extension: .cs.txt, .zip or .dll. Extract archives on your computer first and upload only the .cs.
• The framework isn't running. Check oxide.version (Carbon: c.version), see Oxide and Carbon.

Configuration changes reverted after a restart#

The plugin overwrote the file. Either you edited it while the plugin was running and the plugin saved its own version when unloading, or the JSON was invalid and the plugin created default settings. Follow the safe procedure (unload, edit, load) and check the file with a validator beforehand.

The plugin reports an error reading its configuration#

The error usually contains JsonReaderException or JsonSerializationException and a position like line 12, position 5. There's a JSON error on that line, usually a missing or extra comma or quote. Fix it, or restore your backup.

Players can't use a plugin command#

The players don't have the permission. Most plugins require you to grant permissions to the default group or a specific group. See Permissions on a Rust server.

Further reading#

• Oxide: installing plugins (opens in a new window)
• Oxide: configuring plugins (opens in a new window)
• Oxide: localization (opens in a new window)
• Carbon: documentation for server owners (opens in a new window)
• Rust plugins on umod.org (opens in a new window)