PlaceholderAPI on Your Minecraft Server: What It Is, How to Install It and Why %player_name% Shows Up
PlaceholderAPI is the plugin that makes the player's name, their money, their rank or the number of players online show up on their own in the TAB list, the sidebar, holograms or menus. It does nothing by itself: it turns text like %player_name% into its value for other plugins. Almost everyone who installs it hits the same snag, the text with the percent signs showing in game instead of the value, and it's nearly always a missing expansion.
What a placeholder is and what an expansion is
A placeholder is a slot between percent signs that gets filled in when it's shown: %player_name% becomes the name of whoever sees it, %server_online% the players online and %vault_eco_balance% the player's money. You write it in another plugin's config (the TAB one, the sidebar one, the holograms one) and PlaceholderAPI fills in the value.
Placeholders come in expansions. Some are built into the plugin that provides the data and work without doing anything. Others are a separate .jar you download from PlaceholderAPI's expansion cloud (the eCloud): among them are the most used, Player (%player_…%), Server (%server_…%), Vault (money and ranks), Essentials and LuckPerms. Installing PlaceholderAPI on its own brings none of those.
Two conditions for anything to show: the plugin where you write the placeholder must support PlaceholderAPI (its page says so; TAB, DecentHolograms, DeluxeMenus, AnimatedScoreboard and DiscordSRV do), and that placeholder's expansion must be loaded.
Rather not set it up yourself? Minecraft servers from €6 a month, no contract and a full refund within 72 hours. Or create a free Minecraft server, no card needed.
Installing it
Check your server runs plugins
PlaceholderAPI is a plugin for Paper, Spigot or Purpur; it doesn't work on Fabric, Forge or NeoForge. On NapNodes, Minecraft servers are delivered with Paper.
Install it from the panel
In the panel, «Mods & plugins»: search for PlaceholderAPI and install it. It searches Modrinth for only what works on your version. If you'd rather do it by hand, upload the .jar to the plugins folder from «Files».
Restart
Plugins load at startup. Afterwards you'll see the plugins/PlaceholderAPI folder, with config.yml and the expansions folder, which is where expansions are kept.
Download the expansions you'll use
In the panel's «Console» (without a slash in front): papi ecloud download Player and papi ecloud download Server, the most used ones. If you have an economy, papi ecloud download Vault (with the Vault plugin installed); for LuckPerms ranks, papi ecloud download LuckPerms.
Reload
papi reload loads the newly downloaded expansions without restarting. papi list shows which ones are active.
Testing a placeholder before using it
Before touching another plugin's config, check the placeholder returns a value. In game, as op: /papi parse me %player_name%. It should reply with your name. From the console, which isn't a player, use the name of someone online instead of me: papi parse Name %player_ping%.
If parse returns the value and the other plugin still shows the percent signs, the problem isn't PlaceholderAPI: that plugin doesn't support it, or that particular option in its config doesn't read placeholders. If parse returns the text unchanged, the expansion is missing or it's misspelt (next section).
To see which placeholders an eCloud expansion has: papi ecloud placeholders Player. The full, up-to-date list, including the ones built into each plugin, is on the PlaceholderAPI wiki (wiki.placeholderapi.com).
The most used placeholders
Player (Player expansion): %player_name%, %player_displayname%, %player_ping%, %player_health%, %player_level% and %player_world%.
Server (Server expansion): %server_online% and %server_max_players% (the «12/20» in the tab list), %server_tps_1% (TPS over the last minute; %server_tps_1_colored% colours it by how good it is), %server_ram_used% and %server_uptime%.
Money and rank (Vault expansion, with Vault and an economy plugin such as EssentialsX): %vault_eco_balance_formatted% for the balance, %vault_prefix% and %vault_group% for the prefix and group. With LuckPerms (LuckPerms expansion): %luckperms_prefix% and %luckperms_primary_group_name%.
Statistics (Statistic expansion): %statistic_mine_block:diamond_ore% counts the diamond ore mined, handy for sidebars and leaderboards.
%player_name% shows instead of the name: the causes
The expansion is missing
The most common one. Installing PlaceholderAPI isn't enough: papi ecloud download Player (or whichever you need) and papi reload. papi list tells you which ones are loaded.
You didn't reload
A downloaded expansion does nothing until papi reload or a restart.
It's misspelt
One extra letter or a missing underscore and it's no longer recognised. Compare it with papi ecloud placeholders <expansion> or the wiki, and test it with /papi parse me.
The plugin it gets its data from is missing
The Vault, Essentials and LuckPerms ones need that plugin installed and enabled (green when you type /plugins). Without it, the expansion doesn't load and the console says «Failed to load Expansion class … (Is a dependency missing?)».
The plugin you're writing it in doesn't support it
If /papi parse returns the value but the game doesn't, the fault is in the other plugin. EssentialsX Chat, for example, doesn't read PlaceholderAPI placeholders in the chat format without an extra plugin to feed them in; check each one's documentation.
If «papi ecloud download» downloads nothing
The command needs the server to be able to reach the eCloud over HTTPS. NapNodes servers can: outgoing HTTPS is open (what's blocked is outgoing mail and bursts of connections).
What can happen is that the expansion isn't verified: the download command only fetches verified ones, so nobody can slip in a .jar with malware. In that case, find it on ecloud.placeholderapi.com, download the .jar, upload it from «Files» to plugins/PlaceholderAPI/expansions and type papi reload in the «Console».
Only download expansions from the eCloud or the plugin's official page. An expansion is code that runs on your server with the same permissions as a plugin: before trying anything unusual, take a copy in «Backups».
Frequently asked questions
What is PlaceholderAPI for?
It lets other plugins (TAB, sidebars, holograms, menus) show data such as the player's name, their money, their rank or the players online, by writing placeholders like %player_name% in their config.
Why does %player_name% show instead of the player's name?
Nearly always because the Player expansion is missing: type papi ecloud download Player and then papi reload in the console. Check with /papi parse me %player_name%; if your name shows there, the plugin you wrote it in is the one failing.
How do I download a PlaceholderAPI expansion?
With papi ecloud download <name> (for example, papi ecloud download Server) and then papi reload. If it isn't verified and won't download, get it from ecloud.placeholderapi.com and upload it to plugins/PlaceholderAPI/expansions.
Does PlaceholderAPI work on Fabric or Forge?
No: it's a plugin for Paper, Spigot and Purpur. Fabric has mods that do something similar, but they're different and mods have to be made for them.
Does PlaceholderAPI use a lot of RAM?
Very little: it only translates text when another plugin asks it to. What can weigh is a plugin refreshing lots of placeholders very often (a tab list or sidebar updating several times a second); if you notice lag, raise its refresh interval.
Shall we set it up for you?
Minecraft servers from €6 a month, never oversold: your RAM is yours alone. And if you'd rather start without paying, there's a free Minecraft server, no card needed.
Your server doesn't show up in the game? Check it in a second with “Is my Minecraft server online?”: players, version and MOTD, free. Need a player's UUID for the whitelist or permissions? Look it up here. Handing out enchanted items? Build the command with the /give generator.
Keep reading
- WorldEdit on Your Minecraft Server: How to Install It and the Most Used Commands
Install WorldEdit on your Minecraft server and learn to select with the axe, //set, //replace, //copy, //paste, //undo, schematics and permissions.
- GriefPrevention: Let Every Player Protect Their Base with a Golden Shovel
Install GriefPrevention on your Minecraft server: claim land with the golden shovel, trust friends, claim blocks and the admin commands you'll need.
- Mods and Plugins Together on a Minecraft Server: Hybrids and Alternatives
Can you run mods and plugins together in Minecraft? What Arclight, Mohist and Youer are, their problems, and the mods that do what your plugins do.