Updating

By the end of this page you will know which of the three things people call "updating" you actually want, and what each one does to your world.

They are genuinely different operations, and confusing them is the most likely way to lose something:

1. Updating Osmium — a new binary. Touches no server.
2. Updating a server's Minecraft or loader version — osmium migrate. Touches the jar and every mod.
3. Updating installed mods or plugins — osmium mod update. Touches only those jars.

---

Updating Osmium itself#

Nothing about your servers changes. The manifest and lock formats are versioned, and an older manifest is read and upgraded in place the first time a newer Osmium touches it.

Installed with the install script — run it again. It replaces the binary with the latest release:

$ curl -fsSL https://osmiummc.com/install.sh | sh

On Windows:

PS> irm https://osmiummc.com/install.ps1 | iex

Installed with the Go toolchain — run the same command again:

$ go install github.com/limelamp/osmium@latest

Installed from a release archive — download the new archive from the releases page and replace the binary. If you installed the completion scripts, run osmium completion install again afterwards so they describe the new command set.

Built from source — pull and rebuild:

$ git pull
$ make install

Confirm with osmium --version.

---

Updating a server's Minecraft or loader version#

This is osmium migrate, and it is the only operation that changes what the server runs.

$ osmium migrate -s survival --loader Paper --version 1.21.1

Leave a flag off and Osmium asks for it, using the same steps the interface uses, and finishes on a review screen before anything is touched.

The server must be stopped. Migrating a running server is refused.

What migrate does:

• replaces the server jar with the one for the new loader and version;
• resolves every installed mod and plugin to a build that fits the new target;
• moves anything with no compatible build into a migration_backup folder rather than deleting it;
• leaves the world, server.properties, and every other file in the server folder untouched.

Your world is not converted, rewritten or backed up by this command. Minecraft itself upgrades a world's format when a newer server opens it, and that upgrade is one-way: a world opened by 1.21 cannot be opened by 1.20 again. Take a backup first if the version change is one you might want to walk back:

$ osmium backup -s survival before-1.21
$ osmium migrate -s survival --version 1.21.1

Pinned entries are still pinned after a migration. A pin names one exact build, and that build may not exist for the new Minecraft version — in which case it is one of the things moved to migration_backup. Unpin anything you want re-resolved before migrating:

$ osmium mod unpin sodium -s survival

---

Updating installed mods and plugins#

$ osmium mod update -s survival                 # everything that is not pinned
$ osmium mod update sodium fabric-api -s survival   # only these

osmium plugin update is the same, for plugins/.

What update does:

• looks for newer builds that still fit this server's loader and Minecraft version — it never changes the Minecraft version;
• leaves pinned entries exactly where they are, whether or not you named them;
• prints the whole plan before applying it, and asks before anything is removed;
• writes nothing until every file has arrived and matched its published SHA-1, so a failure halfway through leaves the server as it was.

Your world is not touched. Mod jars are, so a mod that stores data in the world can still make its own mess of it — take a backup before a large update:

$ osmium backup -s survival

To move a single mod deliberately and hold it there:

$ osmium mod add sodium@0.5.8 -s survival

Adding a build by name pins it. osmium mod unpin sodium lets it move with the rest again.

Pre-release builds are excluded unless you ask for them:

$ osmium mod update --pre -s survival

Next#

Uninstalling — and what removing Osmium's config does to servers that already exist.