Screenshot 1 of 1. MinecraftHub-generated cover art for HeadDB: a floating desert block island with server racks, under a night sky
What HeadDB works with.
| Platform | Java Edition |
|---|---|
| Loaders | Folia, Paper |
| Minecraft versions | 1.20, 1.20.6, 1.21.7, 26.1.2, 26.2 |
HeadDB is a head database plugin for Paper and Folia servers. It gives players an inventory menu for browsing, searching and favoriting more than 100,000 heads. It runs on the server side only, so players join with a normal setup and install nothing.
Server software and versions
- Folia: Minecraft 26.1 to 26.2. The newest build needs no dependencies.
- Paper: Minecraft 1.20 to 26.2. The newest build needs no dependencies.
- Bukkit and Spigot: Minecraft 1.20 to 1.21.7, builds stopped after July 2025. The newest build needs no dependencies.
Browsing and search
Players open the menu with /hdb. From there they move through categories, tags and collections, run text search with advanced filters and sorting, and keep favorites per player. Player heads sit apart from the public catalog. Admins decide whether players may obtain only their own head or other players' heads, and whether external profile lookups are allowed.
Control for server admins
- Custom heads, stored locally and never added to the public database.
- Custom categories, tags and collections that sit beside the public ones in the Browse menu.
- Local overrides for name, lore, category, tags, collections and visibility, which can be reset without touching the remote data.
- Optional pricing through Vault and a Vault-compatible economy provider. With economy support off, heads are free.
- Configurable GUI layouts, messages and sounds, plus granular permissions.
Installation
Put the plugin file in the plugins folder and restart, as covered in the plugin install guide. The first start generates config.yml, gui.yml, economy.yml and messages/en-US.yml inside plugins/HeadDB. Grant players headdb.basic, or set up finer permissions.
Admin commands
- /hdb verify and /hdb refresh check and update the remote database.
- /hdb reload reloads the configuration.
- /hdb debug exposes diagnostic information.
Scheduled database refreshes are on by default, so new heads arrive without a manual step. Downloads are verified with SHA-256 before use.
HeadDatabase plugin tutorial and overview
Questions about HeadDB.
4 questions
How do I install HeadDB on my server?
Place the plugin file in the plugins folder of a Paper or Folia server and restart. Review the generated files in plugins/HeadDB, then grant players headdb.basic. Players open the menu in-game with /hdb. The server needs Java 25 or newer and network access for the first database download.
Does HeadDB work on Folia?
Yes. HeadDB lists Paper and Folia support, and the current builds carry both. Spigot and Bukkit builds exist for older releases but have stopped, so new development targets Paper and Folia only.
Does HeadDB need Vault?
No. Vault and an economy provider are only required if you want to charge players for heads. With economy support disabled, every head is free. Pricing can be set for remote heads, player heads, categories, individual heads and a global fallback.
Can I add my own heads to HeadDB?
Yes. Custom heads can be created through the menu or from a compatible held head item and texture value. They can join custom categories, tags and collections. They stay local to your server and are not added to the public database.
