LuckPerms: groups and permissions on a Minecraft server, step by step

LuckPerms is a permission management plugin. It decides who can use which command and feature, and puts players into groups like VIP, Moderator or Admin, including a prefix in chat. We'll go through how permissions work and then build a complete group structure for a typical server, step by step.

How permissions work#

You'll find permission names in each plugin's documentation. On Paper, permissions for Minecraft's own commands look like minecraft.command.<command>, for example minecraft.command.kick or minecraft.command.teleport (the /tp command). If you don't know a permission, LuckPerms can find it for you, see Checking and troubleshooting.

Installation and data storage#

1. In the Plugins tab › Browse, search for LuckPerms and click Install (or upload the file from luckperms.net/download (opens in a new window) to the plugins folder, see Installing plugins).
2. Restart the server.
3. In the console, check that LuckPerms started (the line [LuckPerms] Enabling LuckPerms … with no errors). On first start the plugin downloads its libraries, so startup may take a little longer.

LuckPerms creates a plugins/LuckPerms folder with its settings in config.yml. Where it stores data is set by the storage-method option:

For a single server, keep h2. Setting up MySQL is covered in the article MySQL for plugins. If you change the storage later, the data doesn't move over on its own:

1. Export it with lp export prevod. This creates the file plugins/LuckPerms/prevod.json.gz.
2. Stop the server and change storage-method in plugins/LuckPerms/config.yml (for MySQL, the login details too).
3. Start the server and load the data with lp import prevod.json.gz. Type the file name including the .json.gz extension.

Instead of prevod, you can use any name without spaces or accented characters.

Full rights for yourself#

After installation, nobody except the console and operators can use LuckPerms commands. Operators are allowed to use LuckPerms commands by default (the commands-allow-op: true option in plugins/LuckPerms/config.yml).

1. Join the server so that LuckPerms knows your account.

2. In the Console tab, type:

   lp user <NICK> permission set luckperms.* true

   • lp – short for the LuckPerms command (the long form is luckperms).
   • user <NICK> – we're editing a player. Replace <NICK> with your in-game name, for example Steve.
   • permission set – we're setting a permission.
   • luckperms.* – all LuckPerms permissions, i.e. access to all its commands.
   • true – grant the permission (false would explicitly deny it).

In the game you then use the commands with a slash (/lp …), in the console without one.

Creating groups and inheritance#

We'll build a structure that suits most servers:

default
├── vip
└── helper
    └── moderator
        └── admin
            └── owner

Each group inherits everything from the group above it. So an admin can do everything a moderator can, a moderator everything a helper can, and everyone everything default can. VIP is a separate branch, so VIPs don't get staff rights.

1. Create the groups along with their weights. Type these into the console one by one:

   lp creategroup vip 100
   lp creategroup helper 200
   lp creategroup moderator 300
   lp creategroup admin 400
   lp creategroup owner 500

   • creategroup <group> – creates an empty group. Write names in lowercase without accents or spaces.
   • The number after the name is the weight. A higher weight takes priority. Gaps of a hundred leave room for groups you add later (for example vip-plus with a weight of 150).

2. Set up inheritance:

   lp group vip parent add default
   lp group helper parent add default
   lp group moderator parent add helper
   lp group admin parent add moderator
   lp group owner parent add admin

   • group <group> – we're editing a group.
   • parent add <parent> – the group starts inheriting the parent's permissions. Inheritance chains, so owner gets the permissions of every group below it.

3. Give the groups the names players will see (optional):

   lp group moderator setdisplayname Moderator

   The display name can contain accented characters. This way you can also show the default group as “Player” without changing its actual name.

Permissions for groups#

You add a permission with lp group <group> permission set <permission> [true|false] [context…]. If you leave out the value, true is used.

1. The basics for all players (the default group), an example for EssentialsX:

   lp group default permission set essentials.home
   lp group default permission set essentials.sethome
   lp group default permission set essentials.delhome
   lp group default permission set essentials.spawn
   lp group default permission set essentials.tpa
   lp group default permission set essentials.tpaccept
   lp group default permission set essentials.tpdeny
   lp group default permission set essentials.back
   lp group default permission set essentials.msg
   lp group default permission set essentials.warp
   lp group default permission set essentials.warp.list

   This gives players homes (/home, /sethome, /delhome), a return to spawn, teleport requests (/tpa, /tpaccept, /tpdeny), a return to their last location (/back), private messages and warps.

2. VIPs with more homes and a crafting table anywhere:

   lp group vip permission set essentials.sethome.multiple
   lp group vip permission set essentials.sethome.multiple.vip
   lp group vip permission set essentials.workbench
   lp group vip permission set essentials.hat

   The number of homes for “vip” is set in plugins/Essentials/config.yml in the sethome-multiple section (5 by default), see Recommended plugins.

3. Staff (helper, moderator, admin):

   lp group helper permission set essentials.mute
   lp group helper permission set essentials.kick
   lp group helper permission set coreprotect.inspect
   lp group helper permission set coreprotect.lookup
   lp group moderator permission set essentials.tempban
   lp group moderator permission set essentials.vanish
   lp group moderator permission set essentials.invsee
   lp group moderator permission set essentials.tp
   lp group moderator permission set coreprotect.rollback
   lp group moderator permission set coreprotect.restore
   lp group admin permission set essentials.ban
   lp group admin permission set essentials.unban
   lp group admin permission set essentials.gamemode
   lp group admin permission set essentials.fly
   lp group admin permission set worldedit.*
   lp group admin permission set worldguard.region.*
   lp group owner permission set luckperms.*
   lp group owner permission set essentials.*

   The CoreProtect, WorldEdit and WorldGuard permissions are explained in the article Recommended plugins. The worldedit.* wildcard grants all WorldEdit permissions.

Denials and exceptions#

The value false explicitly denies a permission, even if the group inherits it. Example: by default on Paper, players can list the plugins with /plugins. If you want to hide that:

lp group default permission set bukkit.command.plugins false

The lp group <group> permission unset <permission> command, on the other hand, removes the setting entirely (the permission goes back to “not set”).

Permissions only in some places: contexts#

You can add a context to the end of the command. The permission then only applies under that condition:

lp group vip permission set essentials.fly true world=world
lp group default permission set essentials.home false world=pvp_arena

• world=world – VIPs can only fly in the world whose folder is world (not in the Nether, world_nether).
• world=pvp_arena – /home doesn't work in the arena.

Other contexts are gamemode=creative, or server=<SERVER_NAME> for server networks (the server name is set by the server option in plugins/LuckPerms/config.yml).

Temporary permissions#

lp user <NICK> permission settemp essentials.fly true 1d

settemp adds a permission for a limited time. The duration is written as 30m (minutes), 12h (hours), 7d (days), 1mo (month) or a combination, for example 1mo3d12h.

Chat prefixes#

A prefix is the text in front of a player's name in chat, for example [Admin] Steve: hi. LuckPerms only stores it. It's shown by a plugin that formats chat (for example EssentialsX Chat), which reads it through the Vault plugin. Without both, the prefix won't appear in chat.

1. Set prefixes for the groups:

   lp group vip meta setprefix 100 "&6[VIP] "
   lp group helper meta setprefix 200 "&a[Helper] "
   lp group moderator meta setprefix 300 "&9[Moderator] "
   lp group admin meta setprefix 400 "&c[Admin] "
   lp group owner meta setprefix 500 "&4[Owner] "

   • meta setprefix – sets a prefix and replaces the group's previous prefix.
   • The number (100 to 500) is the prefix priority. When a player belongs to several groups, the prefix with the highest priority is shown. So a moderator who is also a VIP gets the [Moderator] prefix.
   • The text in quotes is the prefix. The quotes are needed because of the space at the end, which separates the prefix from the name.
   • &6, &a … are color codes (table below).

2. Check that your chat plugin reads the prefix: type vault-info in the console. The output must list LuckPerms as the source of permissions and chat.

Put formatting codes (&l, &o, &n) after the color code, for example &c&l[Admin].

Adding a player to a group#

The player should join the server at least once so that LuckPerms knows their account.

lp user <NICK> parent add vip

• parent add <group> – adds a group to the player. Their other groups stay. Useful for giving VIP to a staff member.

lp user <NICK> parent set moderator

• parent set <group> – gives the player only this group and removes the others. Useful for changing someone's rank.

lp user <NICK> parent remove vip

• parent remove <group> – removes the group. If the player has no other group, they go back to default.

lp user <NICK> parent addtemp vip 30d

• parent addtemp <group> <duration> – a group for a limited time (here 30 days), for example a month of VIP. When it runs out, LuckPerms removes it automatically.

The web editor#

Instead of commands, you can edit everything in your browser.

1. Type lp editor in the console.

2. LuckPerms prints a link. Open it in your browser.

3. On the left, pick a group or player. Add permissions in the Add Permission field (the editor suggests known permissions), and change values by clicking in the table. Add a context with the Add Contexts button.

4. Click Save (or Ctrl+S).

5. The editor shows a command in the form /lp applyedits <CODE>. Click it to copy it.

6. Paste it into the console without the slash at the start and press Enter.

   The console prints a summary of the changes. Only now are they saved.

In the editor, weight, prefix and parent are written as special permissions: weight.400, prefix.400.&c[Admin] and group.moderator.

Promotion ladders (tracks)#

A track is a ladder of groups you move players along with a single command. It doesn't affect inheritance.

1. Create a track and add the groups to it in the right order:

   lp createtrack tym
   lp track tym append helper
   lp track tym append moderator
   lp track tym append admin

2. Promote and demote:

   lp user <NICK> promote tym
   lp user <NICK> demote tym

   • promote – moves the player one step up and removes their previous group from the track. If they aren't on the track yet, they get the first group (helper).
   • demote – moves the player one step down.

Checking and troubleshooting#

When you don't know which permission a command needs, use verbose:

1. Type lp verbose record <NICK> in the console.
2. Have the player run the command that isn't working in the game.
3. Type lp verbose upload. LuckPerms prints a link to an overview of all permission checks. Look for the lines with the result false.

A recommended structure for a typical server#

Principles: only give the permissions a group really needs. Add new permissions to the lowest group that should have them, and the higher groups inherit them. Handle exceptions with the value false or a context, not by copying permissions into several groups.

LuckPerms on Fabric, Forge and NeoForge#

LuckPerms also exists as a mod. The commands are the same, the file goes in the mods folder and the settings are in the config folder, in the LuckPerms subfolder. One difference: Fabric doesn't check permissions for Minecraft's own commands, so permissions like minecraft.command.gamemode don't work on Fabric without another mod. Commands from mods that support LuckPerms work normally.

Quick recipes#

Replace <NICK> with the player's in-game name. In the game, type the commands with a slash (/lp …).

LuckPerms on a server network (Velocity)#

When you run several servers connected through a Velocity proxy, you usually want the same groups everywhere. The procedure in a nutshell:

1. Install LuckPerms on every server and on the proxy (the Velocity version). On the proxy, the commands are typed as lpv instead of lp.
2. Create one MariaDB or MySQL database that all instances connect to, see MySQL for plugins.
3. On each instance, edit plugins/LuckPerms/config.yml (with the server stopped):

4. Restart all servers and the proxy. A change made on one server then shows up on the others too.

Setting up the network itself is covered in the article A server network with Velocity.

Verification#

1. Type lp user <NICK> info for a test player. The output shows their groups and prefix.
2. Join as a regular player (without operator status, deop <NICK>) and try commands the group should be able to use, and ones it shouldn't.
3. Send a chat message and check the prefix.

Troubleshooting#

Typing /lp only shows the plugin version#

You don't have permission for any LuckPerms command. Give it to yourself from the console with lp user <NICK> permission set luckperms.* true.

Permissions don't work even though the player is in the group#

• Another permission plugin is on the server (PermissionsEx, GroupManager and the like). LuckPerms has to be the only one; remove the others.
• You're testing as an operator. Operators get plugin permissions automatically, which skews the result. Test without op.
• A typo in the permission name. Check it with lp verbose (above).
• The permission is set to false somewhere. lp user <NICK> permission check <permission> shows where the value comes from.

The prefix doesn't show in chat#

Vault or a chat format plugin is missing. Install Vault (or VaultUnlocked) and EssentialsX Chat and restart the server. In EssentialsX Chat, the chat format must contain {DISPLAYNAME} or {PREFIX}. If a player sees a different prefix than you expect, compare the priorities in lp user <NICK> meta info.

Changes from the web editor didn't take effect#

You didn't run the lp applyedits <CODE> command generated after saving. Save again and run the command.

lp user can't find the player#

The player hasn't joined the server yet, so LuckPerms doesn't know their account. Have them join, or use their UUID instead of the name.

A player in a group has no prefix or permissions after being added with parent set#

Check the group name (lp listgroups). parent set with a group that doesn't exist ends with an error and adds nothing to the player.

Further reading#

• LuckPerms wiki: getting started (opens in a new window)
• LuckPerms wiki: command overview (opens in a new window)
• LuckPerms wiki: prefixes and meta (opens in a new window)
• Paper: command permissions (opens in a new window)