How to Configure LuckPerms on Your Server

LuckPerms is the permissions plugin almost every Minecraft server ends up using. It decides who can run which commands, which rank each player holds, and what prefix shows up next to their name. It is free, it is fast, and once you understand three ideas (permissions, groups and inheritance) the rest of it falls into place.

This guide walks through configuring LuckPerms from a fresh install: giving yourself access, building a set of ranks, adding players to them, using the web editor, and the more advanced pieces like tracks, contexts and temporary ranks. Every command here works on Paper, Purpur and Spigot, and the same commands work on the Fabric, NeoForge and Forge versions of LuckPerms too.

What LuckPerms does, in plain terms

Every command and feature a plugin offers is guarded by a permission node, a dotted string such as essentials.home or worldedit.wand. LuckPerms decides whether a player has a given node.

You could give nodes to each player one by one, but that gets unmanageable fast. Instead you create groups (ranks like member, moderator and admin), give the nodes to the groups, and put players in groups. Groups can inherit from each other, so your moderator rank gets everything a member has without you typing it twice.

One thing LuckPerms does not do on its own is change how chat looks. It stores prefixes and suffixes, but a separate chat plugin has to read them and print them. More on that below.

Install LuckPerms on your server

Download LuckPerms from its official site or its Modrinth page, and pick the build for your server software: Bukkit (which covers Paper, Purpur and Spigot), Velocity or BungeeCord for a proxy, or the Fabric, NeoForge or Forge version for a modded server.

On a CloudNord server you don't need to download anything by hand:

1. Open your server in the client area and go to the Plugins tab (on a Fabric, NeoForge or Forge server, use the Mods tab instead).
2. Search for LuckPerms. The list is already filtered to your Minecraft version and server software.
3. Click Install, then restart the server from the Console.

On the first start LuckPerms creates its folder at plugins/LuckPerms/ (or config/luckperms/ on modded servers), with a config.yml and a small local database. You can open both from the Files tab.

Give yourself access first

LuckPerms commands are themselves permissions, so on a brand-new install nobody can use them yet. The fix is to run one command from the server console, which always has full rights. In the Console tab, type (with no slash, and with your own Minecraft name):

lp user YourName permission set luckperms.* true

From now on you can run /lp commands in game. Being an operator also gives you LuckPerms access on Paper and Spigot by default, but it is cleaner to rely on the permission node and keep the op list short. If you do want to manage operators, the Player Lists tab on your server edits ops.json for you.

Plan your ranks before you type anything

Five minutes with a notepad saves an hour of untangling later. A typical survival server needs four groups:

• default: every player, including people who joined a minute ago. LuckPerms creates this group itself and you can't delete it.
• member: trusted regulars. Homes, warps, maybe a few cosmetic commands.
• moderator: kick, mute, temporary bans, teleport, inspecting grief.
• admin: everything else.

Write down which plugin commands each rank needs. The permission nodes are listed on each plugin's documentation page. EssentialsX, WorldGuard, CoreProtect and the other big plugins all publish full lists.

Create groups and give them permissions

Create the groups:

/lp creategroup member
/lp creategroup moderator
/lp creategroup admin

Then give each group its nodes. The format is /lp group <group> permission set <node> [true|false], and leaving off the value means true:

/lp group default permission set essentials.spawn
/lp group member permission set essentials.home
/lp group member permission set essentials.sethome.multiple
/lp group moderator permission set essentials.kick
/lp group moderator permission set essentials.mute
/lp group admin permission set essentials.*

The * wildcard grants every node under that prefix. Use it for admins, but be careful handing it to anyone else, because it also grants nodes you may never have heard of.

Setting a node to false is just as useful. It explicitly denies something a group would otherwise get, for example a moderator rank that inherits a wildcard but shouldn't be able to clear inventories.

Set up inheritance

Inheritance is what keeps your setup small. Each rank should inherit the one below it:

/lp group member parent add default
/lp group moderator parent add member
/lp group admin parent add moderator

Now a moderator has everything a member has, and a member has everything in default. You only ever add the new nodes at each level.

Give groups a weight

When a player sits in several groups, LuckPerms uses weight to decide which group wins, for things like which prefix is shown. Higher wins:

/lp group member setweight 10
/lp group moderator setweight 50
/lp group admin setweight 100

Add players to groups

There are two ways to put someone in a group, and the difference matters:

/lp user Steve parent set member
/lp user Alex parent add moderator

parent set removes the player from every other group and puts them in just this one. parent add keeps their existing groups and adds another. For a simple rank ladder, parent set is usually what you want. To take a group away, use /lp user Alex parent remove moderator.

Prefixes and suffixes

Prefixes are stored as "meta" on a group. The number is a priority, and the highest priority prefix a player has is the one shown:

/lp group member meta setprefix 10 "&a[Member] "
/lp group moderator meta setprefix 50 "&9[Mod] "
/lp group admin meta setprefix 100 "&c[Admin] "

The & codes are the usual Minecraft colour codes. setprefix replaces any prefix the group already has, so run it again to change one. If the prefix doesn't show up in chat, nothing is wrong with LuckPerms. It needs a chat plugin to display it: a small dedicated one such as LPC, or EssentialsX Chat together with Vault. Both are in the Plugins tab.

Use the web editor for bigger changes

Typing commands is fine for one or two changes. For setting up a whole server, the web editor is much faster. Run:

/lp editor

LuckPerms prints a link. Open it and you get every group and user in your browser, where you can add nodes with autocomplete, drag weights around and edit prefixes. When you're done, press Save in the editor. It gives you an /lp applyedits command with a short code: paste it into the game or the console and every change is applied at once. Nothing on the server changes until you do.

Each editor link is a one-off session, so run /lp editor again next time instead of reusing an old link.

Tracks: promotions in one command

A track is an ordered ladder of groups. It lets you promote and demote people without remembering which rank comes next:

/lp createtrack staff
/lp track staff append member
/lp track staff append moderator
/lp track staff append admin

Then /lp user Steve promote staff moves Steve up one step and /lp user Steve demote staff moves him down. Many servers run two tracks: one for donor or playtime ranks and one for staff, so the two never clash.

Contexts: permissions that only apply sometimes

Any permission, group or prefix can be limited to a context, most commonly a world or a server. Add the context at the end of the command:

/lp group member permission set worldedit.* true world=creative
/lp user Alex parent add builder server=survival

The first line gives members WorldEdit in the creative world only. The second only applies on a backend server named survival. You name each server with the server: setting near the top of its LuckPerms config.yml, which is how one shared setup can treat a lobby, survival and minigames differently.

Temporary permissions and ranks

For trial staff, event rewards or a monthly perk, add a duration and LuckPerms removes it by itself when time is up:

/lp user Steve permission settemp essentials.fly true 1d
/lp user Alex parent addtemp vip 30d

Durations can be written like 30m, 12h, 1d or 1w.

Storage: H2 for one server, MySQL for a network

Out of the box LuckPerms keeps everything in an H2 database file inside its own folder. For a single server that is the right choice, and it is backed up along with the rest of your files.

If you run several servers behind a Velocity or BungeeCord proxy, they should share one database so a rank given on one server applies on all of them. In each server's LuckPerms config.yml, set storage-method to mysql (or mariadb) and fill in the data section with the same connection details everywhere. On CloudNord you can create that database from the Databases tab with New database, which gives you the host, port, user name and password to copy in. Restart each server after changing storage.

Install LuckPerms on the proxy as well. There its command is /lpv on Velocity and /lpb on BungeeCord, so it doesn't clash with /lp on the servers behind it.

To keep servers in sync instantly instead of on a timer, also set messaging-service in the same file. sql works with nothing extra installed, and pluginmsg works when the proxy runs LuckPerms too.

If you are building a network, our guide to running a Minecraft network with a proxy covers the proxy side.

When something doesn't work

Three commands answer nearly every "why can't they do this?" question:

• /lp user Steve info lists Steve's groups and his primary group.
• /lp user Steve permission check essentials.home tells you whether he has a node and where it came from.
• /lp verbose on prints every permission check as it happens. Ask the player to try the command, read which node it checked, then run /lp verbose off.

Verbose mode is the quickest way to find out which node a plugin really wants, since documentation is sometimes out of date. Most problems turn out to be a typo in a node, a player in the wrong group, or a context that doesn't match the world they are standing in.

Frequently asked questions

Is LuckPerms free?

Yes. LuckPerms is free and open source, and there is no paid version.

Do I need Vault for LuckPerms?

Not for permissions. LuckPerms works on its own. Vault is only needed when another plugin, usually a chat or economy plugin, wants to read LuckPerms groups or prefixes through Vault.

Why doesn't my prefix show in chat?

LuckPerms stores prefixes but doesn't format chat. Install a chat plugin such as LPC, or EssentialsX Chat with Vault, and make sure the prefix's priority is higher than any other prefix the player has.

What is the difference between parent set and parent add?

parent set replaces all of a player's groups with one group. parent add adds a group and keeps the ones they already have.

Does LuckPerms work on modded servers?

Yes. There are LuckPerms builds for Fabric, NeoForge and Forge, and the commands are the same. Modded content is only covered as far as each mod checks permissions, so some mods still rely on operator status.

Can I move my LuckPerms setup to a new server?

Yes. Run /lp export backup on the old server, copy the file it creates from the LuckPerms folder to the same folder on the new server, and run /lp import backup there.

Ready to set up your ranks?

LuckPerms rewards a little planning: decide your ranks, build them with inheritance, then use the web editor for the detail. If you are still choosing a home for your server, our Minecraft server hosting installs LuckPerms in one click from the Plugins tab, and our modded Minecraft hosting does the same for Fabric, NeoForge and Forge from the Mods tab.