# How to Install and Configure LuckPerms on Your Minecraft Server (/docs/minecraft/setup-luckperms)



import { Step, Steps } from 'fumadocs-ui/components/steps';

**LuckPerms** is the most-used permissions plugin for Minecraft. It manages groups (ranks), permissions, inheritance, prefixes, and per-world overrides — and it has the best web editor of any permissions plugin, which is reason enough to install it.

LuckPerms supports Bukkit/Spigot/Paper, Folia, Sponge, Velocity, BungeeCord, Forge, NeoForge, and Fabric.

How LuckPerms Works [#how-luckperms-works]

```
Player ──── primary group ──► Group ──── inherits from ──► Group
                                │                            │
                                ▼                            ▼
                          permissions                  permissions
                                │                            │
                                └────── effective set ──────┘
```

* **Groups** hold permissions and metadata (prefix, suffix, weight)
* **Players** belong to one or more groups
* **Groups can inherit** from other groups (e.g., `vip` inherits from `default`)
* **Permissions can be set** at the player level or group level
* **Tracks** are linear group chains for promotion/demotion

Install LuckPerms [#install-luckperms]

<Steps>
  <Step>
    Download LuckPerms [#download-luckperms]

    Go to [luckperms.net/download](https://luckperms.net/download) and pick the build for your platform:

    | Platform                        | File                                                           |
    | ------------------------------- | -------------------------------------------------------------- |
    | Bukkit / Spigot / Paper / Folia | `LuckPerms-Bukkit-X.X.X.jar` → `plugins/`                      |
    | Fabric                          | `LuckPerms-Fabric-X.X.X.jar` → `mods/` (also needs Fabric API) |
    | Forge / NeoForge                | `LuckPerms-Forge-X.X.X.jar` → `mods/`                          |
    | Velocity                        | `LuckPerms-Velocity-X.X.X.jar` → `plugins/`                    |
    | BungeeCord                      | `LuckPerms-Bungee-X.X.X.jar` → `plugins/`                      |
    | Sponge                          | `LuckPerms-Sponge-X.X.X.jar` → `mods/`                         |
  </Step>

  <Step>
    Stop the server [#stop-the-server]

    In the [XGamingServer Panel](https://panel.xgamingserver.com), open **Console** and stop your server.
  </Step>

  <Step>
    Upload the JAR [#upload-the-jar]

    Click **Files** in the sidebar. Upload to `plugins/` (or `mods/`).
  </Step>

  <Step>
    Start the server [#start-the-server]

    Start from **Console**. LuckPerms creates `plugins/LuckPerms/` and a default `default` group.
  </Step>

  <Step>
    Verify [#verify]

    ```
    plugins
    ```

    `LuckPerms` should appear in green.
  </Step>
</Steps>

Quick Start: Create Three Ranks [#quick-start-create-three-ranks]

The most common starter setup is three ranks: member, mod, admin.

<Steps>
  <Step>
    Create the groups [#create-the-groups]

    In **Console**:

    ```
    lp creategroup admin
    lp creategroup moderator
    lp creategroup member
    ```
  </Step>

  <Step>
    Set up inheritance [#set-up-inheritance]

    Have admin inherit from moderator, and moderator inherit from member:

    ```
    lp group moderator parent add member
    lp group admin parent add moderator
    ```

    Now any permission given to `member` applies to all three groups.
  </Step>

  <Step>
    Set group weights [#set-group-weights]

    Higher weight = higher priority for prefix display:

    ```
    lp group member meta setweight 10
    lp group moderator meta setweight 50
    lp group admin meta setweight 100
    ```
  </Step>

  <Step>
    Add permissions [#add-permissions]

    ```
    lp group member permission set essentials.home true
    lp group member permission set essentials.sethome true
    lp group member permission set essentials.spawn true
    lp group member permission set essentials.tpa true
    lp group member permission set essentials.tpaccept true

    lp group moderator permission set essentials.kick true
    lp group moderator permission set essentials.mute true
    lp group moderator permission set essentials.tempban true

    lp group admin permission set essentials.* true
    lp group admin permission set worldedit.* true
    lp group admin permission set minecraft.command.op true
    ```
  </Step>

  <Step>
    Set prefixes [#set-prefixes]

    ```
    lp group member meta setprefix "&7[Member] "
    lp group moderator meta setprefix "&9[Mod] "
    lp group admin meta setprefix "&c[Admin] "
    ```

    For prefixes to show in chat, you need [EssentialsX Chat](/docs/minecraft/setup-essentialsx) and [Vault](/docs/minecraft/setup-vault).
  </Step>

  <Step>
    Assign players [#assign-players]

    ```
    lp user PlayerName parent set member
    lp user AdminName parent set admin
    ```

    The player's primary group is updated immediately — no relog needed.
  </Step>
</Steps>

Use the Web Editor (Recommended) [#use-the-web-editor-recommended]

The web editor is faster than typing commands for any non-trivial setup.

<Steps>
  <Step>
    Generate an editor link [#generate-an-editor-link]

    In Console or in-game:

    ```
    /lp editor
    ```

    LuckPerms uploads your current data and gives you a URL like `https://luckperms.net/editor/abc1234`.
  </Step>

  <Step>
    Edit visually [#edit-visually]

    In the web editor:

    * Drag-and-drop permissions between groups
    * Set inheritance with checkboxes
    * Edit prefixes and metadata
    * Use search to find permission nodes
  </Step>

  <Step>
    Apply changes [#apply-changes]

    Click **Save** in the editor. It generates an apply command. Paste it back into your server console.
  </Step>
</Steps>

> **Web editor data is uploaded.** It's hosted publicly. Use it for normal permission management — don't paste anything sensitive.

Common Commands [#common-commands]

| Command                                               | Description                         |
| ----------------------------------------------------- | ----------------------------------- |
| `/lp editor`                                          | Open the web editor                 |
| `/lp creategroup <name>`                              | Create a new group                  |
| `/lp deletegroup <name>`                              | Delete a group                      |
| `/lp listgroups`                                      | List all groups                     |
| `/lp group <name> info`                               | View a group's perms                |
| `/lp group <name> permission set <perm> [true/false]` | Add a permission                    |
| `/lp group <name> permission unset <perm>`            | Remove a permission                 |
| `/lp group <name> parent add <other>`                 | Set inheritance                     |
| `/lp group <name> meta setprefix "<prefix>"`          | Set chat prefix                     |
| `/lp group <name> meta setsuffix "<suffix>"`          | Set chat suffix                     |
| `/lp group <name> meta setweight <number>`            | Set group weight                    |
| `/lp user <name> info`                                | View a player's groups and perms    |
| `/lp user <name> parent set <group>`                  | Set primary group                   |
| `/lp user <name> parent add <group>`                  | Add an extra group                  |
| `/lp user <name> permission set <perm>`               | Override a perm for one player      |
| `/lp user <name> promote <track>`                     | Promote up a track                  |
| `/lp user <name> demote <track>`                      | Demote down a track                 |
| `/lp createtrack <name>`                              | Create a promotion track            |
| `/lp track <name> append <group>`                     | Add group to a track                |
| `/lp sync`                                            | Sync from database (network setups) |
| `/lp verbose on`                                      | Debug missing permissions           |

Wildcard Permissions [#wildcard-permissions]

| Permission                      | Effect                        |
| ------------------------------- | ----------------------------- |
| `*`                             | All permissions on the server |
| `essentials.*`                  | All EssentialsX permissions   |
| `worldedit.*`                   | All WorldEdit permissions     |
| `essentials.sethome.multiple.*` | Unlimited homes               |
| `minecraft.command.*`           | All vanilla commands          |

> **Warning:** `*` is the equivalent of OP. Only give to trusted admins.

Per-World Permissions [#per-world-permissions]

LuckPerms supports per-world permission contexts:

```
lp group vip permission set essentials.fly true world=creative
```

This grants `essentials.fly` only when the player is in the `creative` world.

Network / BungeeCord Setup [#network--bungeecord-setup]

For multiple backends sharing permissions, use a **MySQL backend**:

In `plugins/LuckPerms/config.yml` on every backend:

```yaml
storage-method: mysql
data:
  address: your-mysql-host:3306
  database: luckperms
  username: luckperms_user
  password: your-password
```

All backends now read/write from the same database. See [Use MySQL Database](/docs/minecraft/use-mysql-database).

Common Issues [#common-issues]

| Problem                                    | Fix                                                                        |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| Permissions don't work                     | Verify with `/lp user <name> info` — check the player has the right groups |
| Permission "not set" warning               | LuckPerms shows missing perms — check spelling, then `lp verbose on`       |
| Prefix not showing                         | Install Vault + EssentialsXChat + LuckPerms — chat plugin must hook Vault  |
| Player has perm but command says no        | OP override is interfering — deop the player                               |
| Group inheritance not working              | Use `parent add`, not `permission set group.X true`                        |
| Web editor link expired                    | Generate a new one with `/lp editor`                                       |
| Changes don't sync across backends         | Set up MySQL storage (see above)                                           |
| Wildcard `*` doesn't grant a specific perm | Some plugins use negative perms — set explicit `true`                      |

Common Mistakes [#common-mistakes]

| Mistake                                                               | Fix                                                 |
| --------------------------------------------------------------------- | --------------------------------------------------- |
| Forgetting `/op` overrides perms                                      | Deop players — use perms instead                    |
| Using `permission set group.admin true` instead of `parent add admin` | The latter is correct for inheritance               |
| Setting prefix without weight                                         | Conflicts with other groups' prefixes — set weights |
| Not restarting after switching from default to MySQL                  | Restart to apply storage change                     |
| Editing the YAML files manually while server is running               | Use commands or the editor instead                  |
| Forgetting to give `essentials.signs.use.*` for player signs          | Many EssentialsX features need granular perms       |

Related Guides [#related-guides]

* [Plugin Setup](/docs/minecraft/plugin-setup)
* [Setup EssentialsX](/docs/minecraft/setup-essentialsx)
* [Setup Vault](/docs/minecraft/setup-vault)
* [Use MySQL Database](/docs/minecraft/use-mysql-database)
* [OP Permissions](/docs/minecraft/op-permissions)