Set up ViaVersion on your Minecraft server

ViaVersion is a plugin that lets players join with a different Minecraft version from the one your server runs. Without it, players need the same Minecraft version as the server. This guide installs it on a Paper server through the Plugins tab.

Checked against ViaVersion 5.12.1 and ViaBackwards 5.12.1, both listing Paper and Minecraft up to 26.3, October 2026.

Pick the right plugins

ViaVersion is the first of a small family, and which parts you need depends on who is joining:

If your server runs the newest Minecraft release, no normal client is ahead of it, so ViaBackwards is the plugin that matters. Players on Bedrock Edition use Geyser instead, not ViaVersion: see Let Bedrock players join your Java server.

Before you start

ViaVersion runs on Paper. Its documentation warns that some Paper forks are not officially supported, so Purpur is worth testing rather than assuming. Spigot is not offered on our panel. On a Fabric server the equivalent is a separate mod called ViaFabric, installed from the Mods tab.

Take a backup in the Backups tab first. Create and restore backups shows how.

Install it

1. Open your server and select Plugins, then make sure Modrinth is chosen in the source chip row at the top of the tab. Hangar works too, since the project publishes there.
2. If players will join with an older version, search for ViaBackwards first and click Install on its row. A prompt reads Needs 1 more add-on and lists ViaVersion: click Install all, and both plugins go in. Skip to step 4.
3. If players will only join with a newer version, search for ViaVersion and click Install on its row. If a Works well with prompt offers optional extras, click Install ViaVersion only to skip them.
4. Open the Console tab and click Restart, or Start if the server is stopped. Plugins load only at startup.
5. When the Done line appears, type plugins in the console. ViaVersion should show in green.
6. Type viaversion list to see which versions connected players are using. With nobody online it answers No players found!.

The panel does not check what a Hangar plugin needs, so on Hangar install ViaVersion yourself before ViaBackwards. If ViaVersion is already in the folder when you install ViaBackwards, the Needs prompt does not appear. You may see a Works well with prompt for optional extras instead: click Install ViaBackwards only to skip them.

Change its settings

Open the File Manager and go to plugins/ViaVersion. Double-click config.yml, edit it and click Save. Then run viaversion reload in the Console with the server running, which covers most changes, or restart the server. Some options need a full restart.

• block-versions and block-protocols list client versions to refuse. Both start empty.
• block-disconnect-msg is the text a blocked player sees. It starts as You are using an unsupported Minecraft version!.
• check-for-updates starts as true.

The commands under viaversion need the viaversion.admin permission, which operators have by default.

Common problems

• Players see You are using an unsupported Minecraft version!. That is the blocked message. Check block-versions and block-protocols in the config.
• A new Minecraft release has no matching ViaVersion yet. ViaVersion is released a few days after a Minecraft update. Click Check for updates in Installed after that, or Update all if the button shows that instead.
• Players cannot use new blocks. ViaVersion keeps older servers playable for newer clients and does not add the newer game's content.
• Odd behavior after updating ViaVersion. Restart the server instead of using /reload. ViaVersion's documentation says a restart takes full effect and a reload may not.