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.
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-consolecommand 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:
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
exitThen restart the server and wait for the Done line:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fExit the log view with Ctrl+C, then check that the plugin responds:
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:
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:
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.
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:
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:
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:
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:
sudo mc-console 'lp verbose off'Add Players to Ranks
# 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.
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:
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:
sudo mc-console 'lp group vip permission set minecraft.command.weather true world=world'To remove it, specify the same context:
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:
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
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:
sudo mc-console 'deop Steve'Back Up Permissions
The following command creates the plugins/LuckPerms/sauvegarde-luckperms.json.gz file:
sudo MC_CONSOLE_WAIT=5 mc-console 'lp export sauvegarde-luckperms'To restore this file, placed in plugins/LuckPerms, specify its extension:
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:
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.serviceTroubleshooting
"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:
sudo journalctl -u minecraft.service --no-pager | grep -i -A5 'luckperms' | grep -iE 'error|exception|caused by' | head -20
df -h /opt/minecraftA 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 verboseto 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.