Install HeadDB

Choose the correct HeadDB build, install it, and complete the first server startup.

HeadDB is the Minecraft plugin that makes the managed catalog available through in-game menus and commands. HeadDB 6.1.0 uses the catalog at headdb.net; it does not use the API or database operated by another HeadDB fork.

Choose one build

Install exactly one jar:

File	Server	Java	Notes
`HeadDB-6.1.0.jar`	Paper or Folia 1.21 or newer	Java 21+	Recommended modern build with revision-based catalog updates.
`HeadDB-6.1.0-legacy.jar`	Bukkit-compatible 1.8.8–1.20.6	The Java version required by the server	Compatibility build that refreshes complete catalog files.

The modern jar declares Paper API version 1.21 and can run on later Paper releases. Do not install both jars, and do not use the modern jar on Spigot or a server older than 1.21. The modern artifact supports Folia: it creates an inventory tree per open and uses concurrent page and navigation registries.

Download releases from GitHub, Modrinth, or Hangar.

Install the plugin

Stop the Minecraft server completely.
Remove any older or duplicate HeadDB jars from plugins/.
Copy the correct HeadDB jar into plugins/.
Start the server and wait for HeadDB to load the catalog.
Run /hdb info to confirm the plugin version and server implementation.
Join the server and run /hdb to open the main menu.

HeadDB has no required companion plugin. Vault and a compatible economy plugin are optional and needed only when purchases are enabled.

The server needs outbound HTTPS access to:

https://headdb.net
https://textures.minecraft.net

Files created on first startup

HeadDB stores its configuration and runtime state under plugins/HeadDB/:

Path	Purpose
`config.yml`	Menus, item text, economy, catalog, indexing, and update settings.
`categories.yml`	Optional server-defined collections of existing head textures.
`sounds.yml`	Interface sound configuration.
`messages/`	Translatable player and command messages.
`catalog-cache.json`	Last-known-good modern catalog and its revision.
`data/data.db`	Player favorites, language, and sound preferences.

Keep preloadHeads: false unless there is a measured reason to change it. The current catalog contains more than 86,000 heads, and the normal lazy-loading path avoids creating every ItemStack during startup.

How catalog updates work

The modern plugin restores catalog-cache.json or downloads a complete snapshot from:

https://headdb.net/api/v1/catalog/snapshot

It then requests changes after its saved revision from:

https://headdb.net/api/v1/catalog/changes

Each change is an upsert containing a complete current head or a remove containing the stable ID to remove. HeadDB applies all pages, rebuilds its indexes and menus, then saves the completed revision. A failed request never replaces the last valid catalog. The default synchronization interval is 15 minutes, and a restart also performs a synchronization.

Uploaded skins are published through MineSkin so the final texture is hosted by Mojang. HeadDB 6.1.0 passes those URLs through Paper's supported PlayerTextures API.

Next steps

Learn the menu, search, and give commands in Commands and permissions.
Review common settings in Plugin configuration.
Integrate another plugin through the Bukkit Java API.

Updating and troubleshooting

To update, stop the server, replace the old jar, and perform a full restart. Do not use /reload. The catalog cache and player database are reusable across a normal update.

If players see The head database is still loading, check the server console for the failed URL and verify outbound HTTPS. If a category is missing for only some players, check its permissions. If a corrected texture still looks old, obtain a new copy of the item: existing inventory items and placed skulls keep the profile data already stored inside them.