LuckPerms Full Setup Guide: Groups, Inheritance, Contexts and Weight

LuckPerms is the industry-standard permissions plugin for Paper, Spigot and Velocity. It replaces PermissionsEx, GroupManager and bPermissions in nearly every modern setup because it is fast, supports every major proxy, exposes a full API and stores data in a format you can inspect directly. This guide covers everything from a blank install to a fully tiered rank system with per-world contexts, weight-based priority and clean inheritance.

Installation and first boot

Drop the LuckPerms jar into your plugins/ folder and restart the server. On first boot it creates plugins/LuckPerms/config.yml. The two settings you should decide immediately:

• storage-method: h2 (file-based, zero setup, fine for single servers), mysql or mariadb (required for networks where multiple servers share the same permission store), or postgresql. For a network, set up MySQL first and point every server at the same database.
• sync-minutes: On a network set this to 3 so permission changes propagate automatically. On a single server leave it at -1.

After restarting with MySQL configured, confirm the connection with /lp info. You should see the storage backend listed as MySQL alongside the LuckPerms version.

Creating your first groups

Every player who has no assigned group falls into the default group. LuckPerms creates this group automatically. Start by giving default the permissions all players should always have:

/lp group default permission set essentials.spawn true
/lp group default permission set essentials.home true
/lp group default permission set essentials.sethome true
/lp group default permission set essentials.warp true
/lp group default permission set essentials.msg true
/lp group default permission set essentials.tpa true

Now create your rank ladder. A typical survival server has something like: default → member → vip → vip+ → mvp → mvp+ on the donor side, and default → helper → mod → admin → owner on the staff side. Create each group:

/lp creategroup member
/lp creategroup vip
/lp creategroup vip+
/lp creategroup mvp
/lp creategroup mvp+
/lp creategroup helper
/lp creategroup mod
/lp creategroup admin

Setting group display names and prefixes

LuckPerms stores prefix/suffix metadata as permission nodes with a special format. To give VIP a green prefix:

/lp group vip meta setprefix 100 "&a[VIP]&r "
/lp group vip meta setsuffix 100 ""
/lp group vip meta set display-name "VIP"

The number 100 is the priority. Higher numbers win when a player is in multiple groups with conflicting prefixes. Keep staff prefixes at a higher priority (e.g. 200) so they always show over donor ranks.

Inheritance — how groups inherit permissions from parents

Inheritance means a group automatically gets every permission its parent has. This is the key to clean rank design. Instead of copying permissions into every group, each rank only defines what is new at that tier:

/lp group vip parent set member
/lp group vip+ parent set vip
/lp group mvp parent set vip+
/lp group mvp+ parent set mvp

Now if you add a permission to member, every VIP, VIP+ and above gets it instantly. The inheritance chain resolves at lookup time, so there is no need to sync anything after changes.

For staff, inherit from the previous staff rank and from the top donor rank if you want staff to have all donor perks:

/lp group helper parent set default
/lp group mod parent set helper
/lp group admin parent set mod
/lp group admin parent add mvp+

Use /lp group admin info to verify the full parent chain. The output shows inherited parents and the effective permission count after inheritance resolves.

Assigning players to groups

/lp user Notch group set member
/lp user Notch group add vip
/lp user Notch group add vip expiry 30d

Use group set to replace all groups with one. Use group add to add a secondary group (e.g. a donor rank on top of a staff rank). The optional expiry flag auto-removes the group after the specified duration — useful for timed ranks sold through a store.

Contexts — per-world and per-server permissions

Contexts let you grant permissions that only apply under specific conditions. The two most common contexts are server (for proxy networks) and world (for per-world permissions on a single server).

Grant a permission only in a specific world:

/lp user Steve permission set essentials.fly true world=survival

Grant a group permission only on a specific proxy server:

/lp group vip permission set essentials.nick true server=lobby

Contexts can be combined. A permission with both a server and world context only applies when both match simultaneously. This is useful for gamemodes where you want tightly scoped permissions — for example, creative-build permissions only in a creative world on the build server:

/lp group mod permission set worldedit.* true server=build world=creative

View all contexts currently active for yourself with /lp context. This is invaluable when debugging why a permission does or does not apply.

Permission weight — resolving conflicts between groups

When a player is in multiple groups and two groups grant conflicting values for the same node, LuckPerms uses weight to determine which group wins. Higher weight takes priority.

/lp group admin meta setweight 200
/lp group mod meta setweight 150
/lp group helper meta setweight 100
/lp group mvp+ meta setweight 90
/lp group mvp meta setweight 80
/lp group vip+ meta setweight 70
/lp group vip meta setweight 60
/lp group member meta setweight 50
/lp group default meta setweight 0

Weight also controls which group's prefix shows in chat (highest weight wins by default). If you use a chat plugin like EssentialsX chat or a dedicated chat formatter, confirm that it reads from Vault, which reads from LuckPerms — the prefix will then respect weight automatically.

Tracks — automated promotion and demotion

A track is an ordered list of groups that defines a promotion ladder. You can promote and demote players along the track with a single command:

/lp createtrack donor
/lp track donor append member
/lp track donor append vip
/lp track donor append vip+
/lp track donor append mvp
/lp track donor append mvp+

# Promote a player one step up the donor track
/lp user Steve promote donor

Tracks are useful for automating rank-up rewards, giving staff a /promote command that cannot accidentally skip ranks, and integrating with store plugins that call LuckPerms commands on purchase.

Bulk editing and importing permissions

For large setups, editing permissions via command is slow. LuckPerms supports a YAML editor accessible through the web panel:

/lp editor

This generates a link to the LuckPerms web editor where you can add, remove and reorder permissions visually, then apply the batch of changes with a single command. This is the recommended approach for initial server setup when you need to configure dozens of groups at once.

You can also export the full permission tree to a file for backup or migration:

/lp export permissions.yml

And import it on another server:

/lp import permissions.yml

Debugging permissions

The most useful diagnostic commands:

• /lp user <name> permission check <node> — shows true/false and which group it comes from.
• /lp user <name> info — lists all groups, contexts and direct permissions.
• /lp verbose on — live-streams permission checks to your console so you can see exactly what a plugin is checking in real time. Turn off with /lp verbose off.
• /lp log recent — shows recent changes to permission data.

Common mistakes to avoid

• Giving * to admin. This grants every permission including dangerous debug commands from every plugin. Instead give explicit top-level wildcards per plugin where needed.
• Forgetting to set weight. Without weight, prefix display order is undefined when a player has multiple groups.
• Not using inheritance. Copying the same 40 permissions into every group manually means any future change requires editing every group individually.
• Mixing OP with LuckPerms. Keep all staff without OP. LuckPerms and OP permissions can conflict and produce confusing behavior. Use /deop on all staff and give them permissions explicitly.

Need hosting with full config access? Astroworld Hosting — Pterodactyl panel, NVMe SSDs, 24/7 support.