Set up PlaceholderAPI on Minecraft

PlaceholderAPI is a shared layer that lets plugins show each other's information. A scoreboard plugin can show a player's name by writing a short tag such as %player_name%. On its own it adds no placeholders. You add them as expansions. It runs only on the server, so players install nothing.

Checked against PlaceholderAPI 2.12.3 on Paper, which Modrinth lists for Minecraft 1.8 to 26.3, October 2026.

What you need

• A Paper, Purpur or Folia server, which shows a Plugins tab under Content in the panel menu. Install Minecraft plugins on Paper or Purpur covers the basics.
• A plugin that reads placeholders, such as TAB. Not every plugin does. EssentialsX Chat, for one, does not support PlaceholderAPI natively.

Install PlaceholderAPI

1. Open the Plugins tab and keep Modrinth selected in the source chip row at the top of the tab.
2. Search for PlaceholderAPI. The listing's description reads "A resource that allows information from your favorite plugins be shown practically anywhere!".
3. Click Install.
4. Open Console and click Restart.

The first start creates plugins/PlaceholderAPI/config.yml. No placeholders come with the plugin, so the next step is needed.

Add an expansion

An expansion holds the placeholders for one plugin or topic. Some come inside the plugin they belong to and need nothing. Others are separate jars on PlaceholderAPI's expansion cloud. To fetch one, run this in the Console, without the slash:

papi ecloud download Player
papi reload

The reload matters: a downloaded expansion is not active until it runs. papi ecloud list all shows what is available, and papi list shows what is active. The cloud download needs your server to reach ecloud.placeholderapi.com. If it fails, use the manual route below.

For Player, one placeholder is %player_name%. papi ecloud placeholders Player lists the rest.

Test a placeholder

In game, run /papi parse me %player_name%. It should answer with your own name. If it prints %player_name% back, the expansion is missing or the name is mistyped. If the test works but another plugin still shows the raw tag, that plugin does not support PlaceholderAPI.

Then put the tag in the other plugin's config, wherever it accepts text, save the file in File Manager and reload that plugin.

Commands and permissions

• papi version shows the installed version.
• papi info <expansion> shows details of an active expansion.
• papi reload reloads the config and registers expansions you just downloaded.
• papi parse <player|me> <text> tests text for a player.

The node placeholderapi.admin covers the general commands and placeholderapi.ecloud.* covers the cloud ones.

Settings

In config.yml, cloud_enabled and detect_malicious_expansions are both true by default. The commands papi ecloud disable and papi ecloud enable turn the connection to the expansion cloud off and on.

If the download fails

Download the expansion jar from the expansion cloud site in your browser. In File Manager, open plugins/PlaceholderAPI/expansions and click Upload, then choose the jar. Run papi register <file name> in the Console, including .jar, for example papi register MyExpansion.jar. If the folder is missing, install PlaceholderAPI and restart first.

Common problems

• An expansion does nothing. Run papi reload after downloading it, and check with papi list that it is active. Then check that the plugin showing the placeholder supports PlaceholderAPI.
• A config file will not load. See How to find and fix YAML and JSON config errors.