How to Add NPCs to a Minecraft Server with Citizens

Q: How do I make a Citizens NPC run a command?

Select the NPC and use /npc command add . Add -p to run it as the clicking player, and use for their name.

Q: Where does Citizens save NPCs?

In plugins/Citizens/saves.yml. Back it up with your world, and edit it only while the server is stopped.

To add NPCs to a Minecraft server, install the Citizens plugin on a Paper or Purpur server by putting Citizens.jar in plugins/ and restarting. In game, run /npc create Guide to spawn an NPC where you stand, /npc skin Notch to give it a player's skin, /npc lookclose so it faces players, and /npc command add -p warp shop to make it run a command when clicked. NPCs save to plugins/Citizens/saves.yml. Commands added without -p run as the server console, so be careful what you add.

What you are working with

Piece	What it is
Citizens	The NPC plugin. Player shaped or mob shaped NPCs that stand, look, talk, walk paths and run commands
`plugins/Citizens/saves.yml`	Every NPC, its position, skin, traits and commands
`plugins/Citizens/config.yml`	Global options such as chat format and default talk range
Denizen (optional)	A scripting plugin built on Citizens for dialogue, quests and shops
A permissions plugin	Controls who may use `/npc`. LuckPerms is the usual pick

Citizens is a Bukkit plugin, so it needs Paper, Purpur or Spigot. It does not run on Vanilla, Fabric, Forge or NeoForge servers.

Step 1: Download the right build

The Citizens download page offers two sources: release builds on SpigotMC, which is a paid listing, and free development builds on the Citizens Jenkins server. Pick the build that supports your Minecraft version. Right after a new Minecraft release, only the newest dev builds support it, and an older Citizens on a new server fails to enable.

Step 2: Install it

Press Backup or copy your world and plugins folder.
Stop the server.
Upload Citizens.jar into plugins/.
Start the server and run /plugins. Citizens should be listed in green.

New to plugins? How to install plugins on a Minecraft server covers the basics.

Step 3: Create and place an NPC

Stand where the NPC should go and run:

/npc create Guide
/npc lookclose

The new NPC is now selected. Most /npc commands act on the selected NPC. To work on another one, look at it and use /npc select, or /npc select <id>. Useful basics:

Command	What it does
`/npc create <name>`	Creates an NPC where you stand. `--type VILLAGER` for a mob shaped one
`/npc select <id>`	Selects an NPC to edit
`/npc tphere`	Moves the selected NPC to you
`/npc lookclose`	Turns its head to follow nearby players
`/npc rename <name>`	Changes the name above its head
`/npc equip`	Opens an editor to give it armour and items
`/npc text`	Sets lines it says when players talk to it
`/npc remove`	Deletes the selected NPC
`/npc list`	Lists your NPCs with their IDs

Step 4: Give it a skin

/npc skin Notch
/npc skin --url https://example.com/myskin.png

The first copies the skin of any Minecraft account by name. The second uses a skin image URL. Add -l to fetch the latest version of a player's skin.

Step 5: Run commands when players click

This is what most servers use NPCs for: a warp NPC at spawn, a shop keeper, a rules board.

/npc command add -p warp shop
/npc command add -r -p spawn
/npc command add give <p> bread 1
/npc command add --cooldown 86400 give <p> diamond 1

Part	Meaning
`-p`	Run as the player who clicked. They need permission for the command
no `-p`	Run as the server console, with full power
`-l` / `-r`	Only on left click / only on right click
`<p>`	Replaced with the clicking player's name
`--cooldown <seconds>`	How often each player can use it
`--permissions <perm>`	Only players with that permission can trigger it
`--cost <amount>`	Charge money, with an economy plugin installed

Check what an NPC runs with /npc command and remove an entry with /npc command remove <id>.

A frozen Minecraft biome with polar bears at sunset, the kind of spawn area a welcome NPC stands in

The gotcha: console commands and who can add them

By default, /npc command add runs the command as the server console, not as the player. The Citizens commands page notes this. Two things follow:

Player commands break without -p. warp shop or spawn run from the console have no player to move, so clicking the NPC does nothing or prints an error in the console. Add -p for anything that should happen to the clicking player, and make sure players have that permission.
Console commands are a security hole if the wrong people can add them. Anyone allowed to use /npc command can make an NPC run op <p> or any other console command. Only give Citizens permissions to people you would trust with the console. With LuckPerms, grant the citizens permissions to your admin group only, see how to install LuckPerms.

Use console commands on purpose, for things a player should not be able to do themselves, like give <p> diamond 1 with a cooldown.

Going further with Denizen

For NPCs that hold conversations, give quests or run shops with menus, Denizen adds a scripting language on top of Citizens. Scripts go in plugins/Denizen/scripts/ as .dsc files, and you attach them to an NPC with an assignment. It is powerful but a project of its own, so start with plain Citizens commands.

Common problems

Citizens shows red in /plugins or does not load: the build does not support your Minecraft version, or the server is not Paper, Purpur or Spigot.
Clicking the NPC does nothing: the command needs -p, or the player lacks permission for it. Check the console for errors.
Skin stays as Steve: the account name is wrong, or the skin server was slow. Run /npc skin <name> again.
NPCs gone after a restart: saves.yml was replaced or edited while the server was running. Edit with the server stopped, or use commands.
Wrong NPC changed: commands act on the selected NPC. Run /npc select first.

NPCs on GamezServers

On a GamezServers Minecraft server, choose the Paper or Purpur server type, upload Citizens.jar to plugins in the Files tab or over SFTP, and restart. The file manager can also download a file from a link straight to the server, handy for Jenkins builds. Press Backup before adding plugins, and your NPCs stay put with the world running around the clock. For more plugin ideas, see best Minecraft server plugins.

FAQ

Is Citizens free?

The development builds on the Citizens Jenkins server are free. The SpigotMC listing is paid and supports the developers.

Does Citizens work on Fabric or Forge?

No. Citizens is a Bukkit plugin and needs Paper, Purpur or Spigot. Fabric and Forge servers need an NPC mod instead.

How do I make a Citizens NPC run a command?

Select the NPC and use /npc command add <command>. Add -p to run it as the clicking player, and use <p> for their name.

Where does Citizens save NPCs?

In plugins/Citizens/saves.yml. Back it up with your world, and edit it only while the server is stopped.