PortableMC

Cross platform command line utility for launching Minecraft quickly and reliably with included support for Mojang versions and popular mod loaders. It is also available as a Rust crate for developers and bindings for C and Python (yet to come).

Table of contents

• Features
• Installation
  • Binaries
  • Cargo
  • PyPI
  • Linux packages
    • Arch Linux
    • NixOS
• Usage
• Contribute
  • Repositories
  • Releasing
  • Contributors
  • Sponsors
• Rust documentation ⇗

Features

• Install and launch a version in 1 command.
• Supports Mojang versions, and many mod loaders which are installed seamlessly: Forge, NeoForge, Fabric, Quilt, LegacyFabric and Babric.
• Automatically fixing known issues of the game, can be disabled if desired;
• Options for supporting unsupported systems and architectures, such as RaspberryPi/Arm;
• And more flags and options to configure the launch...
• Able to launch offline or with a Microsoft account.
• Browse the supported versions, for any kind of versions.
• Very descriptive output and errors, with configurable verbosity.
• Various output mode, including machine-readable output mode.
• Fast parallel downloading of game files.
• Find your system Java runtime, if compatible, and fallback to Mojang provided ones when available.
• Distributed for many mainstream OS and architectures.

Installation

Binaries

You can directly download and run the portable binaries that are pre-built and available as assets on release pages.

These binaries have been compiled using open source tooling available in this repository. You can ensure that these binaries have been compiled by the official PortableMC project by checking the PGP signature of the archive you downloaded, the PGP fingerprint of the PortableMC project is: f659b0f0b84a26cac635d72948caee8dc3456b2f

You can download the full PGP certificate online:

• Ubuntu Keyserver
• Maintainer server

Cargo

If you have a Rust toolchain with Cargo, you can build and install PortableMC and its CLI straight from crates.io, this is where the latest development versions are pushed first, before being built for specific targets.

cargo install portablemc-cli

If you are a developer willing to use PortableMC as a library to develop your own launcher, it is also available on crates.io and docs.rs.

cargo add portablemc

Some examples are available in portablemc/examples, you can run them with cargo run --example <name>.

PyPI

If you have a Python toolchain, you can install portablemc strait from PyPI, both API and CLI are embedded in this package. The API is provided by a native module and is very similar to the Rust API while taking advantage of the class inheritance and standard types of Python. You can read the stub files for more information about the actual interface, and some examples are available in portablemc-py/examples.

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

Linux packages

We try to deploy the package to different Linux packaging repositories, some are managed by maintainers of the project (first-party) and some by external maintainers (third-party).

Arch Linux

Arch Linux packages are maintained by PortableMC team.

• Build from source: portablemc, available on AUR
• Prebuilt binaries: portablemc-bin, available on AUR

Prebuilt binaries requires you to install the PGP certificate, as described above.

NixOS

Nix package is maintained by @TomaSajt, at nixpkgs/portablemc.

Usage

This section shows example usage to get started with PortableMC.

# 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

# Choose your username in offline mode...
portablemc start -u MyUsername

# Authenticate into your Minecraft account...
portablemc auth login
# List your authenticated accounts...
portablemc auth list
# Start the game with your authenticated account...
portablemc start -u <your username> -a

Contribute

Repositories

The source code is currently tracked using Git and hosted on GitHub.

We also have an official team workspace on Codeberg.org where we host a mirror of this repository and the first-party packaging sources.

Releasing

Releasing process is mostly managed by GitHub actions, it reacts to new tags being pushed to the repository by a repository admin. This section is about how to prepare the repository for that releasing process.

To start with, every new release, which can be either a patch, minor or major release, should have an associated branch that will be merged when releasing is done. It should be named patch-<version>, or release-<version>, and created from main. When you have merged everything into that branch and you are ready for doing the release, you should ensure that the project's version has been updated in Cargo.toml to match the branch and the tag you are about to create, and then you can create and push a tag named v<version>, the GitHub pipeline will trigger automatically.

If it make sense to have release candidates or pre-releases, this should be handled on the same branch as the real release: you should append -rc.<num> or -pre.<num> to the final release number.

Once the pipeline is done, a draft release note is attached to that new tag under releases, you should complete it with the actual changelog, and then publish the release note manually. Note that the release artifacts are automatically uploaded and signed by the actions.

When this is all done, you can now merge and delete the version branch.

Then, you should manage the releasing of official third-party packaging, such as portablemc-arch and portablemc-bin-arch.

Contributors

This launcher would not be as functional without the contributors, and in particular the following for their bug reports, suggestions and pull requests to make the launcher better: GoodDay360, Ristovski, JamiKettunen, Maxim Balashov, MisileLaboratory and GooseDeveloper.

There must be a lot of hidden issues, if you want to contribute you just have to install and test the launcher, and report every issue you encounter, do not hesitate!

Sponsors

I'm currently working on my open-source projects on my free time. So sponsorship is an extra income that allows me to spend more time on the project! This can also help me on other open-source projects. You can sponsor this project by donating either on GitHub Sponsors or Ko-fi. I've always been passionate about open-source programming and the relative success of PortableMC have been a first surprise to me, but the fact that people are now considering to support me financially is even more rewarding! Huge thanks to Erwan Or and user10072023github for their donations!