On this page
- Install LuckPerms on your server
- Who can run the commands
- Plan your rank ladder before typing commands
- Work with the default group, not against it
- Create the groups and set inheritance
- Give each group its permissions
- Limit a permission to one world or server
- Hand out a permission for a limited time
- Add chat prefixes with the right priority
- Install something that actually shows the prefix
- Put players in groups and promote them with a track
- Check your work and use the web editor
Key takeaways
6- Plan groups, parents and weights first, then create them with /lp creategroup and parent add.
- The default group cannot be renamed or deleted; use setdisplayname to show it as Member.
- Prefix priority is the number in meta addprefix, and the highest one wins.
- LuckPerms does not format chat: install Vault plus a chat plugin such as EssentialsX Chat to show prefixes.
- Use a track and /lp user promote to move staff up the ladder.
- Networks need a shared database such as MySQL for every LuckPerms install.
This guide is for owners of Paper or Spigot servers who want proper ranks: members, a supporter rank and a staff team, each with their own permissions and chat prefix. By the end you will have a working rank ladder built with LuckPerms, prefixes that show in chat, and a one-command way to promote players.
Install LuckPerms on your server
LuckPerms is a free, open source permissions plugin (MIT licence). Its Modrinth page lists support for Paper, Spigot, Folia, Velocity, BungeeCord, Fabric, Forge and more, from 1.8.8 up through 1.21.x, and it shows around 2.8 million downloads there.
Download the Bukkit jar for a Paper or Spigot server, then get it into the plugins folder:
- Stop the server, or run
stopin its console. - Copy the jar into the plugins folder, for example
scp LuckPerms-Bukkit.jar user@host:/opt/minecraft/plugins/. - Start the server again with your usual start script.
- Open your server and press Stop in the Console.
- Go to the File Manager, open
pluginsand upload the jar (or upload it over SFTP using the details on the Settings page). - Press Start and watch the Console for LuckPerms loading.
- Stop the server from the panel's main page.
- Open Files (or connect over FTP with the panel's FTP details) and upload the jar into
plugins. - Start the server and check the console for errors.
After the first start you will find a LuckPerms folder inside plugins with a config.yml. The default storage is H2, a file based database, which is fine for a single server.
Who can run the commands
On Bukkit and Spigot, anyone with OP can use LuckPerms commands by default. Give yourself OP from the console, set up the ranks below, then put yourself in the admin group. Commands start with /lp in game. In the server console you can type them without the slash.
Plan your rank ladder before typing commands
A small, clear plan makes everything after it easier. A common starting layout looks like this:
| Group | Who gets it | Inherits from | Weight |
|---|---|---|---|
| default | Every player, automatically | Nothing | 0 |
| vip | Supporters | default | 10 |
| mod | Moderators | default | 50 |
| admin | Server admins | mod | 100 |
Inheritance means a group gets every permission of its parent. So you only add what is new at each step: mods get moderation commands, and admins get everything mods have plus a few extras.
Work with the default group, not against it
LuckPerms puts every player in a group called default when they join. That group cannot be renamed or deleted, by design, so new and old players never end up in different "starter" groups. If you want it to show as "Member", change the display name instead:
/lp group default setdisplayname MemberCreate the groups and set inheritance
- Create each group:
/lp creategroup vip /lp creategroup mod /lp creategroup admin - Link them with parents so permissions flow down the ladder:
/lp group vip parent add default /lp group mod parent add default /lp group admin parent add mod - Set weights so LuckPerms knows which group ranks higher:
/lp group vip setweight 10 /lp group mod setweight 50 /lp group admin setweight 100
Give each group its permissions
Permissions are nodes such as minecraft.command.ban. Each plugin lists its own nodes on its download page or wiki. Set one with true to allow it or false to deny it:
/lp group mod permission set minecraft.command.kick true
/lp group mod permission set minecraft.command.ban trueTo take one away again, use unset:
/lp group mod permission unset minecraft.command.banLimit a permission to one world or server
Most permission commands accept contexts at the end. This lets a node apply only in one place, for example a perk that only works in the main world:
/lp group vip permission set some.plugin.perk true world=worldHand out a permission for a limited time
settemp takes a duration, which suits event rewards or trial perks:
/lp group vip permission settemp some.plugin.perk true 7dAdd chat prefixes with the right priority
Prefixes are stored as meta on the group. The number before the text is the priority: a higher number wins when a player has more than one prefix.
/lp group vip meta addprefix 10 "&a[VIP] "
/lp group mod meta addprefix 50 "&9[Mod] "
/lp group admin meta addprefix 100 "&c[Admin] "Because admin inherits mod, an admin technically has both prefixes. LuckPerms sorts them by weight and picks the highest, so only [Admin] shows. If two prefixes share a weight, the one closest to the player in the inheritance tree is used. Keep a trailing space inside the quotes so the name does not touch the tag.
Install something that actually shows the prefix
This is where most first setups go wrong. LuckPerms stores the prefix but does not format chat itself. On Bukkit based servers you need a chat plugin that reads prefixes through Vault. Vault is a free API plugin that lets other plugins talk to permission, chat and economy systems without each one hooking every plugin separately.
The LuckPerms docs list several chat formatters that work through Vault, including EssentialsX Chat, VaultChatFormatter and ChatEx. EssentialsX is a free, open source suite with over 130 commands for Paper and Spigot, and many servers already run it, which makes its chat module an easy pick.
Put players in groups and promote them with a track
To add a player to a group directly:
/lp user Steve parent add vipFor staff ladders, a track is cleaner. A track is an ordered list of groups, and promoting moves a player one step along it.
- Create the track and add groups in order:
/lp createtrack staff /lp track staff append mod /lp track staff append admin - Promote or demote a player:
/lp user Steve promote staff /lp user Steve demote staff
Tracks only handle promotion and demotion. They do not change inheritance, so keep the parent add links from earlier in place.
Check your work and use the web editor
A few commands confirm everything is wired up the way you planned:
/lp user Steve infoshows a player's groups and meta./lp user Steve permission check minecraft.command.banshows whether a node resolves to true or false./lp group mod listmemberslists everyone in a group.
Once the basics are in, /lp editor gives you a link to the LuckPerms web editor. It shows every group, permission and prefix on one page, which is much quicker for bulk changes than typing commands. Make your edits there, save, and follow the instruction it gives to apply them on the server.
Before big permission changes, take a backup of the plugins/LuckPerms folder (or your database, if you moved to MySQL). On a VPS that is a simple copy, on Pterodactyl the Backups tab covers it, and on Multicraft you can download the folder from the Files page.
Frequently asked questions
Why is my LuckPerms prefix not showing in chat?
LuckPerms stores prefixes but does not format chat. On Bukkit based servers you need Vault and a chat plugin that reads prefixes through it, such as EssentialsX Chat. Also check the prefix weight, since a higher weighted prefix from another group will win.
Can I rename the LuckPerms default group?
No. The default group cannot be renamed or deleted. The LuckPerms docs recommend changing how it looks with /lp group default setdisplayname, or having default inherit from another group you create.
Do LuckPerms tracks give players permissions?
No. Tracks only define an order of groups for promote and demote commands. Permissions still come from the groups and their parent links, so set up inheritance separately.
Do I need MySQL for LuckPerms?
Not for a single server, where the default H2 file storage works. If you run several servers behind Velocity or BungeeCord, every LuckPerms install should use the same remote database, such as MySQL.
