EN

Game servers

How to Manage Ranks and Permissions with LuckPerms

Install LuckPerms on your Paper Minecraft server, create ranks, assign permissions and prefixes, then verify and back up your configuration.

7 min read, updated on 18 November 2026

On this page

LuckPerms is a plugin that decides what each player is allowed to do on your server. This guide explains how to install it, create a rank hierarchy (player, VIP, moderator, administrator), add your players to it and check the result.

Prerequisites

  • A Paper server, with the mc-console command set up in the Install and Update Plugins on Paper guide
  • No other permissions plugin installed: LuckPerms must be the only one
  • Your Minecraft username, and players who have already connected at least once

In this guide, Steve and Alex are examples: replace them with real usernames.

Key Concepts

Concept Meaning
Permission A right expressed as text, for example minecraft.command.ban. Its value is true (granted) or false (denied)
Group A set of permissions assigned to players: this is your rank
Parent A group that is inherited from. A player inherits from their groups, and a group can inherit from another
Weight A group's priority in case of conflict. The highest number wins
Context A condition for applying a permission, for example a specific world
Track A ladder of ranks used to promote or demote a player

All players belong to the default group by default, which exists as soon as the plugin is installed.

Install LuckPerms

Download the Bukkit/Paper version into the plugins folder:

Terminal
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
URL=$(curl -fsSL https://metadata.luckperms.net/data/all | jq -r '.downloads.bukkit')
curl -fLO "$URL"
ls -l LuckPerms-*.jar
exit

Then restart the server and wait for the Done line:

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

Exit the log view with Ctrl+C, then check that the plugin responds:

Terminal
sudo mc-console 'lp info'

The response shows the LuckPerms version and the storage type in use.

Choose the Storage

By default, LuckPerms saves its data in a local H2 database, the plugins/LuckPerms/luckperms-h2-v2.mv.db file. This suits a single server, and you do not need to change anything.

If you prefer readable, editable files, set storage-method: yaml in plugins/LuckPerms/config.yml, then restart the server. If you run several servers that share the same ranks, you need a remote database such as MySQL or MariaDB. Make this choice now: it is easier before you create your groups.

Give Yourself Access to the Commands

Right after installation, nobody can use /lp in-game. Only the console has access. Give yourself full rights on LuckPerms:

Terminal
sudo mc-console 'lp user Steve permission set luckperms.* true'

You can then use /lp in-game, or continue from the console as in the rest of this guide.

Create the Ranks

Here is the example hierarchy. Leave gaps between the weights so you can insert a rank later.

Group Weight Inherits from Role
default 1 none All players
vip 10 default Privileged players
moderator 50 vip Moderation
admin 100 moderator Administration

Create the groups and their weights:

Terminal
sudo mc-console 'lp creategroup vip'
sudo mc-console 'lp creategroup moderator'
sudo mc-console 'lp creategroup admin'
sudo mc-console 'lp group default setweight 1'
sudo mc-console 'lp group vip setweight 10'
sudo mc-console 'lp group moderator setweight 50'
sudo mc-console 'lp group admin setweight 100'

Then define the inheritance. Inheritance is passed down: admin also receives the rights of vip and default.

Terminal
sudo mc-console 'lp group vip parent add default'
sudo mc-console 'lp group moderator parent add vip'
sudo mc-console 'lp group admin parent add moderator'

Assign Permissions

Minecraft commands use permissions of the form minecraft.command.<command>. Give moderators what they need to kick and ban, and give administrators additional rights:

Terminal
sudo mc-console 'lp group moderator permission set minecraft.command.kick true'
sudo mc-console 'lp group moderator permission set minecraft.command.ban true'
sudo mc-console 'lp group moderator permission set minecraft.command.pardon true'
sudo mc-console 'lp group admin permission set minecraft.command.gamemode true'
sudo mc-console 'lp group admin permission set minecraft.command.whitelist true'

To remove a permission, or to explicitly deny it:

Terminal
sudo mc-console 'lp group moderator permission unset minecraft.command.pardon'
sudo mc-console 'lp group vip permission set minecraft.command.kick false'

unset deletes the entry, while false actively denies the right, even if it is inherited from elsewhere. These two commands are examples: run them only if you want these changes.

To find out which permissions a plugin uses, check its documentation. You can also observe the ones the server checks when a player types a command:

Terminal
sudo mc-console 'lp verbose on Steve'

Have the player type the command, read the logs with sudo journalctl -u minecraft.service -n 30 --no-pager, then turn off the monitoring:

Terminal
sudo mc-console 'lp verbose off'

Add Players to Ranks

Terminal
# Replaces all of the player's groups with this rank
sudo mc-console 'lp user Steve parent set moderator'

# Adds a rank without removing the others
sudo mc-console 'lp user Alex parent add vip'

# Removes a rank
sudo mc-console 'lp user Alex parent remove vip'

# Gives a rank for 30 days
sudo mc-console 'lp user Alex parent addtemp vip 30d'

Changes apply immediately, with no restart.

Create a Promotion Track

A track lets you move a player up or down one step without having to remember rank names. It does not change inheritance.

Terminal
sudo mc-console 'lp createtrack staff'
sudo mc-console 'lp track staff append default'
sudo mc-console 'lp track staff append moderator'
sudo mc-console 'lp track staff append admin'
sudo mc-console 'lp user Alex promote staff'
sudo mc-console 'lp user Alex demote staff'

Add Prefixes

A prefix is displayed in front of the username. Its weight decides which one is used when a player inherits several. Codes such as &c set the color:

Terminal
sudo mc-console 'lp group vip meta setprefix 10 "&6[VIP] "'
sudo mc-console 'lp group moderator meta setprefix 50 "&9[Modo] "'
sudo mc-console 'lp group admin meta setprefix 100 "&c[Admin] "'

Keep the single quotes around the full command and the double quotes around the prefix.

Limit a Permission to a World

Add a context at the end of the command. The main world is called world with the default configuration:

Terminal
sudo mc-console 'lp group vip permission set minecraft.command.weather true world=world'

To remove it, specify the same context:

Terminal
sudo mc-console 'lp group vip permission unset minecraft.command.weather world=world'

Use the Web Editor

If you prefer a graphical interface, LuckPerms offers an editor in the browser:

Terminal
sudo MC_CONSOLE_WAIT=5 mc-console 'lp editor'

Open the link displayed, make your changes, then save. If the editor gives you a command to run, run it in the console to apply the changes. Do not share this link: it gives access to editing your permissions.

Verify the Result

Terminal
sudo mc-console 'lp listgroups'
sudo mc-console 'lp group moderator info'
sudo mc-console 'lp group moderator listmembers'
sudo mc-console 'lp user Steve info'
sudo mc-console 'lp user Steve permission check minecraft.command.kick'
sudo mc-console 'lp user Steve meta info'

You should find your four groups, Steve in moderator, the minecraft.command.kick permission set to true and the [Modo] prefix.

Then run a real test with an account that is not an operator. An operator already has most rights, which hides configuration errors. Remove that status if needed:

Terminal
sudo mc-console 'deop Steve'

Back Up Permissions

The following command creates the plugins/LuckPerms/sauvegarde-luckperms.json.gz file:

Terminal
sudo MC_CONSOLE_WAIT=5 mc-console 'lp export sauvegarde-luckperms'

To restore this file, placed in plugins/LuckPerms, specify its extension:

Terminal
sudo MC_CONSOLE_WAIT=5 mc-console 'lp import sauvegarde-luckperms.json.gz'

Regularly copy this file off the server, since a backup kept in the same place would disappear with it.

Update LuckPerms

Drop the new version into plugins/update, then restart. Paper replaces the old file at startup:

Terminal
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
URL=$(curl -fsSL https://metadata.luckperms.net/data/all | jq -r '.downloads.bukkit')
curl -fLO "$URL"
exit
sudo systemctl restart minecraft.service

Troubleshooting

"You do not have permission to use this command!"

Your account does not have access to /lp. Give yourself luckperms.* from the console, as shown above.

"A user for Steve could not be found"

The username is misspelled, or this player has never connected. Check the spelling and ask them to connect a first time.

"A group named vip could not be found"

The group does not exist yet. Check the list with sudo mc-console 'lp listgroups', then create it with lp creategroup.

"Cannot execute command 'lp' in plugin LuckPerms … plugin is disabled"

LuckPerms failed to start. Look for the first error in the logs:

Terminal
sudo journalctl -u minecraft.service --no-pager | grep -i -A5 'luckperms' | grep -iE 'error|exception|caused by' | head -20
df -h /opt/minecraft

A full disk (No space left on device) or a folder not owned by minecraft prevents the plugin from creating its files. In the latter case, run sudo chown -R minecraft /opt/minecraft/server, then restart the server.

A permission does not work

  • Check it with lp user Steve permission check <permission>
  • Make sure no other permissions plugin is installed with sudo mc-console plugins
  • Test with a non-operator account
  • See whether a higher-weight group denies it with false
  • Use lp verbose to see the exact name of the permission being checked

The prefix does not appear in chat

First check that it is saved with lp user Steve meta info. If it is, the problem lies with the display: install Vault and a chat plugin. If two prefixes have the same weight, give them different weights.

Bedrock players are not recognized

With Floodgate, Bedrock usernames start with a dot, which LuckPerms rejects by default. The steps to follow are in the Welcome Bedrock Players with Geyser and Floodgate guide.

To go further, see the official LuckPerms wiki.