PortableMC: a command line Minecraft launcher with mod loader support

One command from version list to running game

PortableMC is described as a cross platform command line utility for launching Minecraft quickly and reliably, with support for Mojang versions and popular mod loaders. The first item in its feature list is the one that defines the tool: install and launch a version in 1 command. Everything else supports that promise. The version catalogue is browsable with a search command that filters by channel and limits the number of entries, so a user can see which versions exist and pick one without leaving the terminal. Output is described as very descriptive, with configurable verbosity, and there is a machine-readable output mode for the cases where the launcher is driven by a script rather than a person. The audience is players who are comfortable with a terminal and system administrators or power users who want to launch a game in a headless or scripted context.

Mod loaders installed as part of the launch

The launcher supports Mojang versions and a list of mod loaders that it installs as part of the launch: Forge, NeoForge, Fabric, Quilt, LegacyFabric and Babric. That list is the point of the tool: the loader installation is part of the launch command rather than a separate installer with its own interface. The same launcher therefore covers the vanilla client and the modded case without a second tool in the workflow. Alongside that, the README lists automatic fixing of known issues of the game, which can be disabled if desired, and options for supporting unsupported systems and architectures, with RaspberryPi and Arm given as the example. Those two options are the difference between a launcher that assumes a desktop PC and one that runs on a small single board computer or an unusual CPU, at the cost of the guarantees that come with a supported configuration.

Java runtime discovery and the Mojang fallback

The Java runtime is the part of Minecraft launching that usually goes wrong, and PortableMC addresses it in two steps. The README states that the tool finds your system Java runtime if it is compatible, and falls back to Mojang provided ones when they are available. So the launcher prefers what is already installed on the machine, which keeps the download small and the version under your control, and only reaches for the vendor supplied runtime when the local one does not work. A launcher that always downloaded its own runtime would be simpler but would ignore a Java version the user needs for another tool. The trade-off is that compatibility checking is a decision the tool makes on your behalf, and the README does not describe the exact compatibility criteria, so a system with an unusual Java installation is the case to test first.

Offline play and Microsoft account authentication

The launcher can start the game offline or with a Microsoft account, and the authentication commands are separate subcommands under auth. There is a login command to authenticate into your Minecraft account, a list command to show which accounts are already authenticated, and the start command takes a flag to launch using an authenticated account. Offline mode is the simpler path: the username is passed directly on the start command, so no credentials are stored and the game runs in a mode where the server does not verify identity. Both are supported in the same binary, and the choice is per launch rather than a global setting, which is what makes the tool usable on a shared or temporary machine as well as on a personal one.

The command surface, shown as the README shows it

The usage section of the README is a list of commands with the options that go with them, and it is short enough to read in one go:

# Start the latest Mojang release, with a random username and default options...
portablemc start

# Start a specific version, let's say 1.16.5...
portablemc start 1.16.5
# You can list the Mojang versions...
portablemc search
# Search on the release versions, and limit to 10 entries...
portablemc search --channel release -l10

Further down the same list the account commands appear, with login, list, and a start invocation that passes the username together with the flag for using an authenticated account. Two other features are worth noting before you install anything. The launcher downloads game files in parallel, which matters on a fresh installation where the bulk of the data is the game itself, and it offers various output modes including a machine-readable one, so the same binary can be used from a script that needs to parse what happened. The README also states that the binaries are distributed for many mainstream operating systems and architectures, so the same commands work across platforms.

Four ways to install, and how to check a binary

The installation section covers four routes. Prebuilt portable binaries are attached as assets to the release pages, and the README explains how to be sure they are the official ones: check the PGP signature of the downloaded archive against the project fingerprint, and the certificate can be fetched from an Ubuntu keyserver or from the maintainer server. That is a stronger guarantee than a checksum alone, since the signature covers the archive. For Rust users with a Cargo toolchain, the CLI is installed straight from crates.io, and the README notes that the latest development versions are pushed there first, before being built for the specific targets:

cargo install portablemc-cli

Python users have a PyPI package that embeds both the API and the CLI, where the API comes from a native module and is described as similar to the Rust API while using Python's class inheritance and standard types, with stub files and examples in the repository:

pip install portablemc
# or... pipx run portablemc
# or... uvx portablemc (or inside venv: uv pip install portablemc)

Linux packaging is handled partly by the project and partly by outside maintainers. On Arch Linux the team maintains both a source package and a prebuilt binary package in the AUR, and the prebuilt one requires you to install the PGP certificate as described above. On NixOS the package is maintained by someone else in nixpkgs. The distinction between first-party and third-party packages is stated explicitly, and it is worth remembering which one you are installing.

One workspace behind the CLI, and a tag driven release process

The Cargo manifest shows the shape of the project. It is a workspace with five members: xtask, portablemc, portablemc-cli, portablemc-ffi and portablemc-py, with the core library and the CLI as the default members. The workspace uses edition 2024 and declares a minimum Rust version of 1.88.0, and the licence is Apache-2.0. The dependencies describe what the tool does at the edges: reqwest with rustls for network calls, clap for the command line interface, xmlparser for parsing, and the archive and compression crates for handling game files. The release process is described in the README and is mostly automated: GitHub Actions reacts to a new tag pushed by a repository admin, the version in Cargo.toml is expected to match the branch and the tag, and the tag is named v followed by the version. Development happens on the develop branch, and the project keeps a mirror on Codeberg alongside GitHub. The visible releases are v5.0.6 on 2026-10-18, v5.0.5 on 2026-09-09 and v5.0.4 on 2026-06-12, and the last push was on 2026-10-18.

Editorial conclusion

PortableMC fits a player who wants a launcher that can be driven from a script, a terminal or a remote session, and a Rust developer who wants to embed the launcher logic in their own tool through the portablemc crate. It does not fit someone who needs a graphical server list, a mod browser or a profile editor. Verify first that the game launches on your platform and that your mod loader version is in the supported list, and if you use the prebuilt binaries, check the PGP signature against the project fingerprint before running them.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. theorzr/portablemc on GitHub