LuckPerms setup: groups, tracks, prefixes, the web editor and per-server permissions

LuckPerms is the permissions plugin that almost every Java server runs, and for good reason: it is free, it runs on Paper, Fabric, NeoForge, Velocity and BungeeCord from one download page, and it stores everything in a database instead of a hand-edited YAML file. The setup that trips people is not installing it. It is understanding that groups inherit, weights decide conflicts, tracks turn groups into a ladder, and prefixes only appear once a separate chat plugin asks LuckPerms for them.

This guide builds a working server from an empty plugins folder: a default group, three ranks on a track, a staff group, prefixes showing in chat, and the per-server contexts you need once you move to Velocity. Every command is copied from the LuckPerms command reference.

Install

1. Download the build for your platform from luckperms.net/download: Bukkit for Paper and Spigot, Fabric or NeoForge for modded, Velocity or BungeeCord for a proxy. The Modrinth listing carries the same jars.
2. Drop it in plugins/ (or mods/) and start the server. LuckPerms writes config.yml and, by default, an H2 database file. The wiki calls H2 "efficient" and it needs no setup, so leave it on a single server.
3. Install Vault as well on Bukkit-based servers. It is the bridge most chat, shop and economy plugins use to ask "what is this player's prefix" or "what group are they in."
4. Give yourself the admin group. From console: lp user YourName parent add admin once the group exists (next section). Ops still work, but LuckPerms is the system now, and the wiki discourages relying on op.

Groups, inheritance and weight

A group is a named bundle of permissions. Every player is in default whether you touch it or not, so default is where survival basics go. Ranks are extra groups that inherit from the one below them, so you never repeat a permission. Build a ladder from console:

lp group default permission set essentials.home true
lp group default permission set essentials.sethome true
lp group default permission set essentials.tpa true

lp creategroup vip 10
lp group vip parent add default
lp group vip permission set essentials.sethome.multiple.vip true
lp group vip permission set essentials.nick true

lp creategroup mvp 20
lp group mvp parent add vip
lp group mvp permission set essentials.fly true

lp creategroup mod 50
lp group mod parent add default
lp group mod permission set essentials.kick true
lp group mod permission set essentials.tempban true

Two rules make this work. Inheritance is recursive: mvp inherits vip, which inherits default, so an MVP has everything. Weight settles conflicts: when two groups a player is in disagree on the same node, the group with the higher weight wins, and the same rule picks which prefix shows. The number after creategroup is the weight; you can change it later with /lp group <group> setweight <weight>. Keep staff weights above donor weights so a moderator who also bought MVP shows as a moderator.

A rank ladder with a track

A track is an ordered list of groups. Once the ladder is a track, "promote this player" is one command and works from any plugin that calls it (rank-up plugins, vote rewards, a store webhook).

lp createtrack ranks
lp track ranks append default
lp track ranks append vip
lp track ranks append mvp

lp user Steve promote ranks     # default -> vip
lp user Steve promote ranks     # vip -> mvp
lp user Steve demote ranks      # mvp -> vip

Keep staff off the player track. Give staff a separate staff track (helper, mod, admin) so promoting a moderator never touches their donor rank and vice versa. The ranks guide has ladders by game mode and the pricing side.

Prefixes need a chat plugin

Set the prefix on the group with a priority. The wiki's own example is /lp group admin meta addprefix 100 "&c[Admin] "; setprefix does the same but replaces any prefix already set in that context:

lp group vip meta setprefix 10 "&a[VIP] "
lp group mvp meta setprefix 20 "&b[MVP] "
lp group mod meta setprefix 50 "&9[Mod] "
lp group admin meta setprefix 100 "&c[Admin] "

When a plugin asks for a player's prefix, LuckPerms collects every prefix the player has or inherits, sorts by that priority number, and returns the highest. That is why the numbers climb with the ladder. Then the part everyone misses: the wiki states plainly that "LuckPerms does not handle any of the chat formatting for you." Install a chat formatter that reads Vault. On Paper, EssentialsX Chat is the common choice; VaultChatFormatter, ChatEx and VentureChat are the others the wiki names. EssentialsX's config.yml already defaults to format: '<{DISPLAYNAME}> {MESSAGE}', and {DISPLAYNAME} combines prefix, name and suffix, so once Vault and EssentialsX Chat are present the prefix appears with no further edits.

If it does not, the FAQ's first step is /lp user <user> info, which shows whether a prefix is actually resolving for that player. If it resolves there and not in chat, the chat plugin is the problem, not LuckPerms. For tab list and name tags, TAB reads the same Vault data; PlaceholderAPI users get %luckperms_prefix% from the LuckPerms expansion.

The web editor

Typing every node is slow. /lp editor uploads your current groups, users and tracks to a session at luckperms.net and prints a link. In the browser you can add permissions in bulk, set parents, weights, prefixes, suffixes and contexts, and drag groups on tracks. When you click save, the editor gives you a command in the form /lp applyedits <code>; run it on the server and the changes land. Nothing applies until you do, which is why you can safely share an editor link with a co-owner.

Contexts and per-server permissions on Velocity

A context is a condition on a permission or a parent. LuckPerms ships two: world, read from the game, and server, read from the server key at the top of each installation's config.yml. Append the context to any command:

lp group default permission set minecraft.command.gamemode true server=creative
lp group vip parent add builder server=creative world=plots
lp user Luck parent add donor server-type=skyblock

The last line uses a static context from contexts.json, which the wiki suggests for grouping several servers of one type (three skyblock backends all set to server-type=skyblock) so one command covers them. A permission set with a server context overrides the same node set globally on that server, which is how you give /gamemode on creative without giving it on survival.

On a network the wiki's network installation page comes down to four settings, applied on the proxy and every backend:

# config.yml on each backend (the proxy uses the same storage block)
server: survival                # unique per backend: hub, survival, creative...
storage-method: mysql           # mysql, mariadb, postgresql or mongodb; never H2 on a network
data:
  address: db.example.com:3306
  database: luckperms
  username: luckperms
  password: change-me
messaging-service: pluginmsg    # one proxy: pluginmsg. multiple proxies: redis
sync-minutes: -1                # with a messaging service there is no need to poll

"All instances of LuckPerms must be connected to the same storage system," in the wiki's words, and that is the part people get wrong: a backend still on its own H2 file will have different groups from the rest. pluginmsg pushes changes over player connections and only works with a single proxy; redis is the choice once you have two. The proxy side of this lives in the Velocity setup guide.

Essential commands

Common mistakes

• Giving default everything. Then wondering why new players can /gamemode. Start from nothing and add nodes as players ask; /lp verbose tells you the exact node each time.
• Expecting prefixes without a chat plugin. LuckPerms stores them; EssentialsX Chat or an equivalent displays them, and Vault connects the two.
• Reusing an old editor session. Apply, then open a new one. Otherwise the second apply can undo the first.
• H2 on a network. Works on one server, breaks on two. Move to MySQL before the second backend, with /lp export and /lp import to carry the data.
• Mixing staff and donor ranks on one track. A moderator who buys VIP either loses mod or loses VIP. Two tracks, weights that put staff on top.
• Setting a node to false when you meant to unset it. false is an explicit deny that beats inherited true. Use permission unset to simply remove it.
• Forgetting the server key. Every backend left on the default name shares one context, and server=survival matches nothing.

With ranks in place, put them where players look before they join: name the ranks and what they include in your listing description, tag the modes, and claim the listing from its server page so the description is yours to keep current. New server? Listing is free.

Quick questions