Installation

By the end of this page you will have the osmium binary on your PATH, tab completion working, and a Java runtime the server can actually use.

Java comes first#

Osmium is a single static binary with no runtime of its own. It does not install, bundle or manage a Java runtime, and a Minecraft server cannot start without one. Install a JRE or JDK before you create a server.

Which Java a server needs follows from its Minecraft version. These are the versions osmium doctor checks against:

Minecraft version	Java needed
1.21 and newer	21
1.20.5 – 1.20.6	21
1.18 – 1.20.4	17
1.17.x	16
1.16.5 and older	8

Check what you have:

bash

$ java -version

Once a server exists, osmium doctor compares the Java on your path against what that server's Minecraft version needs and says so plainly.

Supported platforms#

Release archives are built for:

OS	Architectures
Linux	`amd64`, `arm64`
macOS	`amd64`, `arm64`
Windows	`amd64`, `arm64`

The binary is under 15 MB on every supported platform, and nothing is installed alongside it.

Osmium also needs a terminal with UTF-8 and 256 colours. The interface has a minimum size of 60 columns by 18 rows.

Install with the script#

The recommended way. It downloads the right release for your OS and architecture, checks it against the published SHA-256 checksum, and installs it into your user directory, so it needs no sudo or administrator prompt.

Linux and macOS:

bash

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

This installs to ~/.local/bin/osmium. If that directory is not on your PATH, the script prints the line to add to your shell's startup file. On macOS it usually is not.

The script needs curl or wget, tar, and sha256sum or shasum.

Windows, in PowerShell:

powershell

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

This installs to %LOCALAPPDATA%\Programs\osmium\osmium.exe and adds that folder to your user PATH. Open a new terminal afterwards so the change is picked up.

Both scripts read two optional environment variables:

Variable	Default	What it does
`OSMIUM_VERSION`	the latest release	Install a specific release, e.g. `v0.1.1`
`OSMIUM_INSTALL_DIR`	`~/.local/bin`, or `%LOCALAPPDATA%\Programs\osmium` on Windows	Install somewhere else

For example, to install a specific version:

bash

$ curl -fsSL https://osmiummc.com/install.sh | OSMIUM_VERSION=v0.1.1 sh

To read a script before running it, open install.sh or install.ps1 in your browser.

Install with the Go toolchain#

Needs Go 1.25 or newer.

bash

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

This puts the binary in $(go env GOPATH)/bin. If osmium is not found afterwards, that directory is not on your PATH.

Install from a release archive#

Download the archive for your OS and architecture from the releases page, unpack it, and put osmium somewhere on your PATH.

bash

$ tar -xzf osmium_0.1.1_linux_amd64.tar.gz
$ sudo mv osmium /usr/local/bin/

Each archive also carries README.md, LICENSE, NOTICE and a completions/ folder with the scripts for bash, zsh and fish. A checksums.txt is published beside the archives.

Planned install methods#

None of these exist yet. They are listed so you know what is coming and do not go looking for one that is not there.

An .msi installer for Windows.
Package manager builds: Homebrew, apt, dnf and pacman.

To do as each one lands, replace its bullet with a section holding the real command. Do not document one before it works.

Build from source#

Needs Go 1.25 or newer, git, and make.

bash

$ git clone https://github.com/limelamp/osmium.git
$ cd osmium
$ make build        # builds ./bin/osmium
$ make install      # installs into $(go env GOPATH)/bin

make on its own lists every target. make snapshot builds the release artefacts locally without tagging anything.

Verify the install#

bash

$ osmium --version

It prints the version, the commit it was built from, the date, and the Go toolchain and platform — which is exactly what a bug report needs:

osmium 0.1.1 (4fd7613, 2026-09-24)
go1.25.3 on linux/amd64

A binary built without version stamps calls itself dev.

Shell completion#

Osmium completes server names, your installed mods and plugins, the server software it can install, and released Minecraft versions. Install it once:

bash

$ osmium completion install

It writes the script into the directory your shell reads completions from and tells you where that was. Open a new shell afterwards. The shell is taken from $SHELL, or you can name one: osmium completion install zsh.

To place the script yourself, print it instead:

bash

$ osmium completion bash > /etc/bash_completion.d/osmium
$ osmium completion zsh  > "${fpath[1]}/_osmium"
$ osmium completion fish > ~/.config/fish/completions/osmium.fish

PowerShell has no directory it loads completions from. Add this line to the file $PROFILE names:

osmium completion powershell | Out-String | Invoke-Expression

Next#

Quickstart — from here to a running server in eight steps.