---
title: "PlaceholderAPI Setup: Install Expansions and Placeholders | ZCS"
description: "Placeholders show up in half the plugins on a server (TAB, scoreboards, chat formats), but PlaceholderAPI itself does nothing until expansions are installed."
url: "https://www.zcraftstudios.com/blog/placeholderapi-setup-guide"
updated: "2026-10-20T07:16:50.972429+00:00"
source: "ZCraft Studios"
---

> Site index for AI agents: https://www.zcraftstudios.com/llms.txt (full reference: https://www.zcraftstudios.com/llms-full.txt). Every page is available as Markdown by adding `.md` to its URL or sending `Accept: text/markdown`.

1. [Home](https://www.zcraftstudios.com/)
2. [Blog](https://www.zcraftstudios.com/blog)
3. PlaceholderAPI Setup: Install Expansions and Placeholders

[ All posts](https://www.zcraftstudios.com/blog)

# PlaceholderAPI Setup: Install Expansions and Placeholders

ZCraft StudiosOct 3, 2026Updated Oct 20, 2026

Placeholders show up in half the plugins on a server (TAB, scoreboards, chat formats), but PlaceholderAPI itself does nothing until expansions are installed.

## In this guide

- [Install the Base Plugin](#install-the-base-plugin)
- [Install Expansions](#install-expansions)
- [Finding Available Placeholders](#finding-available-placeholders)
- [Testing a Placeholder](#testing-a-placeholder)
- [Using Placeholders in Other Plugins](#using-placeholders-in-other-plugins)
- [Common Issues](#common-issues)
- [How to diagnose a placeholder that displays as text](#how-to-diagnose-a-placeholder-that-displays-as-text)
- [Official documentation and links](#official-documentation-and-links)
- [An operational test worth running](#an-operational-test-worth-running)

## Setting Up PlaceholderAPI: Installing Expansions and Using Placeholders

_PlaceholderAPI is the plugin behind almost every dynamic value shown in TAB, scoreboards, and chat formats, but it ships with nothing usable until expansions are added._

A placeholder is a short code like `%player_name%` that gets replaced with a real value at display time. PlaceholderAPI itself is just the engine. The actual placeholders (player balance, ping, world, rank) come from separate expansion files.

## Install the Base Plugin

[PlaceholderAPIA resource that allows information from your favourite plugins be shown practically anywhere!On Modrinth ](https://modrinth.com/plugin/placeholderapi)

Download PlaceholderAPI from the project linked above. Check the supported Minecraft version, server platform, Java requirement and dependencies for the selected release.

1. Back up the server files and any plugin database.
2. Stop the server before changing JAR files. Put the compatible plugin build and its required dependencies in the correct plugin folder.
3. Start the server and read the startup log. Resolve missing dependencies or version errors before editing the generated configuration.
4. Stop the server, make one small configuration change, then restart and test it with a non-operator account.

Confirm PlaceholderAPI loads after a clean restart. Test the feature you need with an ordinary player account before adding optional integrations.

## Install Expansions

Expansions are installed from in-game or console, not by downloading jars manually:

```
/papi ecloud download player
/papi ecloud download vault
/papi ecloud download luckperms
/papi reload
```

Each expansion adds a specific set of placeholders: `player` covers basics like `%player_name%` and `%player_ping%`, `vault` adds economy placeholders like `%vault_eco_balance%`, and `luckperms` adds `%luckperms_prefix%` and similar.

## Finding Available Placeholders

```
/papi ecloud list
```

lists every expansion available in the online repository. For placeholders already installed:

```
/papi list
```

shows every active placeholder registered on the server right now.

## Testing a Placeholder

```
/papi parse me %player_name% has %vault_eco_balance% coins
```

runs the placeholder replacement against your own player and prints the result. It's the fastest way to confirm an expansion actually works before wiring it into a config file.

## Using Placeholders in Other Plugins

Once installed, placeholders just get typed directly into whatever config supports them, such as TAB's `config.yml`, a scoreboard plugin's lines, or a chat format:

```
format: '%luckperms_prefix% %player_name%&7: &f%message%'
```

Not every plugin supports PlaceholderAPI placeholders. A plugin needs to specifically declare a "PlaceholderAPI hook," which most modern config-heavy plugins (TAB, DeluxeMenus, FeatherBoard) do.

## Common Issues

- **A placeholder returns the raw code instead of a value**: this almost always means the expansion for it isn't installed, or hasn't been reloaded with `/papi reload` after installing.
- **Expansion install fails**: occasionally caused by the eCloud repository being temporarily unreachable; retrying after a few minutes usually resolves it.
- **Conflicting placeholder names**: rare, but two expansions registering the same placeholder key will have one silently override the other depending on load order.

## How to diagnose a placeholder that displays as text

A placeholder such as `%player_name%` may show literally instead of showing a player's name when the required expansion is missing, a plugin does not support PlaceholderAPI, or the display plugin has not refreshed its content.

A reliable troubleshooting order is:

1. Confirm PlaceholderAPI appears in the loaded plugins list and the console does not show startup errors.
2. Check whether the placeholder belongs to PlaceholderAPI itself or to a separate expansion.
3. Download only the needed expansion using the current official expansion instructions.
4. Use PlaceholderAPI's parse or evaluation tools on a known online player before testing another plugin's scoreboard or chat format.
5. Reload only when the extension documentation recommends it, then verify the final display from a normal player account.

Avoid installing every expansion. Each extra integration creates more dependencies, and some placeholders perform additional work when refreshed frequently.

### Example implementation checklist

| Item | What to verify |

| --- | --- |

| Placeholder syntax | Both percent signs and the identifier are correct |

| Expansion | Installed and enabled |

| Display plugin | Supports PlaceholderAPI |

| Refresh interval | Appropriate for how often the value changes |

| Fallback | Missing values do not break the layout |

[PlaceholderAPI's official wiki](https://wiki.placeholderapi.com/) is the best place to check current expansion installation and command syntax.

[TABAn all-in-one solution that worksOn Modrinth ](https://modrinth.com/plugin/tab-was-taken)

_Tablist example from the official TAB project gallery. [Official source](https://modrinth.com/plugin/tab-was-taken/gallery). Illustrative publisher image._

## Official documentation and links

- [Official project repository](https://github.com/PlaceholderAPI/PlaceholderAPI)
- [Setting Up TAB: Tablist and Scoreboard Customization](https://www.zcraftstudios.com/blog/tab-plugin-tablist-scoreboard-setup)

[PlaceholderAPIA resource that allows information from your favourite plugins be shown practically anywhere!On Modrinth ](https://modrinth.com/plugin/placeholderapi)

## An operational test worth running

An expansion installation is not the same as successfully rendering a placeholder. Confirm expansions load on startup, then test one placeholder in the exact consuming plugin, such as TAB or a scoreboard. If raw token text appears, inspect expansion names, player context and refresh behavior before changing unrelated configurations.

## Resources for this topic

- [Premium TAB & Scoreboard Config | Minecraft Tablist and Scoreboard UI](https://www.zcraftstudios.com/products/premium-tab-scoreboard-configuration)

## Continue reading

- [LuckPerms Config, Placeholders and Verbose Guide](https://www.zcraftstudios.com/blog/luckperms-config-placeholders-verbose-guide)
- [Dynmap Setup Guide: Install, Render and Secure](https://www.zcraftstudios.com/blog/dynmap-setup-guide)
- [BlueMap Setup Guide: Install a 3D Web Map](https://www.zcraftstudios.com/blog/bluemap-web-map-setup)

[ Previous guide Setting Up Geyser and Floodgate for Bedrock Cross-Play](https://www.zcraftstudios.com/blog/geyser-floodgate-bedrock-crossplay-setup)[ Next guide BlueMap Setup Guide: Install a 3D Web Map](https://www.zcraftstudios.com/blog/bluemap-web-map-setup)