EN

Game servers

How to Install and Configure EssentialsX

Install EssentialsX on your Paper Minecraft server: homes, warps, teleportation, kits, economy and chat, with the right LuckPerms permissions.

7 min read, updated on 18 November 2026

On this page

EssentialsX adds the commands players expect to your server: /home, /spawn, /tpa, /warp, /msg, plus kits and an economy. This guide explains how to install it on Paper, grant the right permissions and adjust the most useful options.

Prerequisites

In this guide, Steve is an example: replace it with a real username.

Choose the Right Version

The version to install depends on your Minecraft version. Check it with sudo mc-console version.

Minecraft EssentialsX to install
26.2 or 26.3 2.22.1 development build
26.1.2 or 1.21.11 2.22.0 stable release

Choose the Modules

EssentialsX is split into several files, and only the first one is required.

Module Role In this guide
EssentialsX Core commands, kits, economy Required
EssentialsX Spawn Spawn point, /spawn, /setspawn Installed
EssentialsX Chat Chat format, prefixes and suffixes Installed
EssentialsX AntiBuild Allow or deny building through permissions Optional
EssentialsX Protect World settings: creeper damage, fire spread Optional
EssentialsX GeoIP Approximate player location Optional
EssentialsX Discord and Discord Link Discord bridge and linking Optional
EssentialsX XMPP XMPP bridge, legacy module Optional

Install Vault and EssentialsX

Vault allows EssentialsX to read LuckPerms groups and prefixes. Without it, prefixes and group-related features do not work.

Download Vault, then the three modules from the development build, suited to Minecraft 26.3:

Terminal
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
curl -fL -o Vault.jar https://github.com/MilkBowl/Vault/releases/latest/download/Vault.jar
BASE="https://ci.ender.zone/job/EssentialsX/lastSuccessfulBuild"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
    FICHIER=$(curl -fsSL "$BASE/api/json?tree=artifacts%5BfileName%5D" | jq -r --arg m "$MODULE" '.artifacts[].fileName | select(startswith($m + "-"))')
    curl -fL -o "$FICHIER" "$BASE/artifact/jars/$FICHIER"
done
ls -l Vault.jar EssentialsX*.jar
exit

For Minecraft 26.1.2 or 1.21.11, use the stable release instead, in place of the loop above:

Terminal
BASE="https://github.com/EssentialsX/Essentials/releases/download/2.22.0"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
    curl -fLO "$BASE/$MODULE-2.22.0.jar"
done

Restart the server and wait for the Done line:

Terminal
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f

Verify the Installation

Exit the log view with Ctrl+C, then run:

Terminal
sudo mc-console plugins
sudo mc-console vault-info
sudo mc-console 'essentials version'

You should find:

  • Essentials, EssentialsChat, EssentialsSpawn, LuckPerms and Vault in the plugin list
  • Permission: LuckPerms and Chat: LuckPerms in the vault-info response
  • Economy: Essentials Economy in that same response
  • the same version for all modules in essentials version

The configuration files are located in /opt/minecraft/server/plugins/Essentials.

Grant Permissions to Players

Operators have access to everything. Other players have no access to any EssentialsX command until you grant them the corresponding permission.

Give the common commands to all players:

Terminal
for PERM in spawn home sethome delhome tpa tpaccept tpdeny back warp warp.list msg afk list motd rules help balance pay kit kits.tools; do
    sudo mc-console "lp group default permission set essentials.$PERM true"
done

Then complete the higher ranks:

Terminal
for PERM in sethome.multiple sethome.multiple.vip fly; do
    sudo mc-console "lp group vip permission set essentials.$PERM true"
done
for PERM in tp tphere kick mute tempban; do
    sudo mc-console "lp group moderator permission set essentials.$PERM true"
done
for PERM in setspawn setwarp delwarp eco createkit; do
    sudo mc-console "lp group admin permission set essentials.$PERM true"
done
Command Effect Permission
/spawn Return to the spawn point essentials.spawn
/sethome [name] and /home [name] Create a home and go to it essentials.sethome, essentials.home
/delhome <name> Delete a home essentials.delhome
/tpa <player> Request to teleport to a player essentials.tpa
/tpaccept and /tpdeny Accept or decline a request essentials.tpaccept, essentials.tpdeny
/back Return to the previous position essentials.back
/warp [name] List warps or go to one essentials.warp, essentials.warp.list
/msg <player> <message> and /r <message> Private message and reply essentials.msg
/balance and /pay <player> <amount> Balance and payment essentials.balance, essentials.pay
/kit [name] List kits or receive one essentials.kit, essentials.kits.<name>

The full list of permissions is available on the project's website.

Adjust the Configuration

Open the file as the minecraft user:

Terminal
sudo -u minecraft nano /opt/minecraft/server/plugins/Essentials/config.yml

In nano, Ctrl+W lets you search for an option. Edit the existing lines instead of adding new ones, and use only spaces for indentation.

YAML
# Message language (this line is commented out by default)
locale: en

# Wait between two teleports, in seconds
teleport-cooldown: 30

# Delay before teleporting, canceled if the player moves or is attacked
teleport-delay: 3

# Starting balance and currency
starting-balance: 100
currency-symbol: '€'
currency-symbol-suffix: true

The number of homes is set per rank. A player without essentials.sethome.multiple can only have one. With this permission, they get the default value, and essentials.sethome.multiple.vip gives them the vip value:

YAML
sethome-multiple:
  default: 3
  vip: 5
  staff: 10

Apply your changes without restarting:

Terminal
sudo mc-console 'essentials reload'

Set the Spawn Point and Warps

These commands are typed in-game, at the desired location, with an operator account or a member of the admin group:

Text
/setspawn
/setspawn newbies
/setwarp boutique

/setspawn sets the general spawn point. /setspawn newbies sets the one for new players, used through the newbies option in config.yml:

YAML
newbies:
  announce-format: '&dWelcome {DISPLAYNAME}&d to the server!'
  spawnpoint: newbies
  kit: tools

The specified kit is given on first connection, without checking permissions. Set kit: '' to disable it.

Create a Kit

Kits are stored in plugins/Essentials/kits.yml:

Terminal
sudo -u minecraft nano /opt/minecraft/server/plugins/Essentials/kits.yml

Add your kit to the kits: section. delay is the waiting time in seconds between two uses, and -1 makes it usable only once:

YAML
kits:
  depart:
    delay: 86400
    items:
      - stonesword 1
      - stonepickaxe 1
      - bread 16

Reload the configuration and allow the kit:

Terminal
sudo mc-console 'essentials reload'
sudo mc-console 'lp group default permission set essentials.kits.depart true'

Display Ranks in Chat

With EssentialsX Chat, Vault and LuckPerms, the chat format is set in the chat section of config.yml:

YAML
chat:
  radius: 0
  format: '{DISPLAYNAME}&7:&r {MESSAGE}'

{DISPLAYNAME} already contains the LuckPerms prefix and suffix, so do not add {PREFIX} next to it, or the prefix will appear twice. radius: 0 sends messages to the whole server.

Apply with sudo mc-console 'essentials reload', then write a message in-game: the prefix defined in LuckPerms should be displayed.

Manage the Economy

From the console, you can change the balance of a player who has already connected:

Terminal
sudo mc-console 'eco give Steve 100'
sudo mc-console 'eco take Steve 25'
sudo mc-console 'balance Steve'

Thanks to Vault, other compatible plugins can use this economy.

Verify the Result

Connect with a non-operator account that is a member of the default group, then try:

Text
/sethome maison
/home maison
/spawn
/kit tools
/balance

Each command should work without the You do not have access to that command message. If you enabled locale: en, replies are displayed in English.

Back Up and Update

The plugins/Essentials folder contains the configuration, player data and warps:

Terminal
sudo tar -czf /opt/minecraft/backups/essentials-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server/plugins Essentials

Always update all modules at the same time, as they must have the same version. For a development build:

Terminal
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
BASE="https://ci.ender.zone/job/EssentialsX/lastSuccessfulBuild"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
    FICHIER=$(curl -fsSL "$BASE/api/json?tree=artifacts%5BfileName%5D" | jq -r --arg m "$MODULE" '.artifacts[].fileName | select(startswith($m + "-"))')
    curl -fL -o "$FICHIER" "$BASE/artifact/jars/$FICHIER"
done
exit
sudo systemctl restart minecraft.service

Troubleshooting

"You are running an unsupported server version!"

This version of EssentialsX does not support your Minecraft version. Install the build indicated in the table at the beginning of this guide.

"Version mismatch! Please update all Essentials jars to the same version"

The modules do not all have the same version. Replace them together, then restart the server. Check that no module still has two files with ls /opt/minecraft/server/plugins.

"You do not have access to that command"

The player does not have the permission. Check it, for example for /home:

Terminal
sudo mc-console 'lp user Steve permission check essentials.home'

/r uses the essentials.msg permission, and /spawn requires the EssentialsX Spawn module.

"You cannot set more than 1 homes"

The player has reached their limit. Give them essentials.sethome.multiple and, if needed, a rank such as essentials.sethome.multiple.vip.

"Detected supported permissions plugin LuckPerms without Vault installed"

Vault is missing or did not load. Check that it appears in sudo mc-console plugins, then check the output of sudo mc-console vault-info.

"The file is broken and Essentials can't open it"

A YAML file contains an error, often a tab or incorrect indentation. The logs show which file is affected. Fix it or restore your backup, then restart the server.

A command from another plugin is overridden

If two plugins provide the same command, use the full form, for example /essentials:home. To permanently give priority to the other plugin, add the command to disabled-commands in config.yml.

To go further, see the official EssentialsX wiki.