Package: portablemc
Portable Minecraft LauncherA fast, reliable and cross-platform command-line Minecraft launcher and API for developers.
Including fast and easy installation of common mod loaders such as Fabric, Forge, NeoForge and Quilt.
This launcher is compatible with the standard Minecraft directories.This launcher is tested for Python 3.8, 3.9, 3.10, 3.11, 3.12.Table of contentsInstallationWith pipWith Arch LinuxCommandsStart MinecraftAuthenticationUsername and UUIDCustom JVMServer auto-connectLWJGL version and ARM supportFix unsupported systemsMiscellaneousSearch for versionsAuthentication sessionsShell completionOffline supportCertifi supportContributeSetup environmentContributorsSponsorsAPI Documentation (v4.2) ⇗InstallationWith pipThis launcher can be installed usingpip.  On some linux distribution you might have to
usepip3instead ofpipin order to run it on Python 3. You can also usepython -m pipif thepipcommand is not in the path and the python executable is.pipinstall--userportablemc[certifi]After that, you can try to show the launcher help message usingportablemcin your
terminal. If it fails, you should check that the scripts directory is in your user path
environment variable. On Windows you have to search for a directory at%appdata%/Python/Python3X/Scriptsand add it to the user's environment variablePath.
On UNIX systems it's~/.local/bin.You can opt-out from thecertifioptional feature if you don't want to depend on it,
learn more in theCertifi supportsection.[!TIP]
It's recommended to keep--userbecause this installs the launcher for your current
user only and does not pollute other's environments, it is implicit if you are not an
administrator and if you are, it allows not to modify other users' installations.With Arch LinuxFor Arch Linux users, the package is available asportablemcin theAUR.This is currently maintained by Maks Jopek, Thanks!CommandsArguments are split between multiple commands.
For exampleportablemc [global-args] <cmd> [args].
You can use-hargument to display help(also works for every command).By default the launcher will run any command from the OS standard.minecraftdirectory
(check wiki for more information). You can
change this directory using--main-dir <path>global argument.You may also need--work-dir <path>to change the directory where your saves, resource
packs and all "user-specific" content is stored. This can be useful if you have a shared
read-only main directory (--main-dir) and user-specific working directory (for example
in.minecraft, by default it's the location of your main directory). The launcher also
stores cached version manifest and authentication database in the working directory.The two arguments--main-dirand--work-dirmay or may not be used by commands,
but they are always valid to use, allowing you to define command aliases for running
PortableMC.Another argument,--timeout <seconds>can be used to set a global timeout value that
will be used for all network connections.The general output format of the launcher can be changed using the--output <mode>with
one of the following modes:human: Human readable output, translated messages, formatted tables and tasks,
default if stdout if not a TTY.human-color: Same ashumanbut with some color where relevant, like tasks states
and game logs, default if stdout is a TTY.machine: Machine readable output, with one light per state change.The verbosity of the launcher can be adjusted if you encounter issues, using multiple-varguments (usually-vthrough-vvv). It's very useful to maintainers when fixing
issues.Start MinecraftThe first thing you may want to do is install and start Minecraft, to do so you can use
theportablemc start [args] [version]command. This command will install every component
needed by the version before launching it. If you provide no version, the latest release
is started, but you can specify a version to launch, or a version alias:releaseorsnapshotfor the latest version of their type.In addition to Mojang's vanilla versions, the launcher natively supports common mod
loaders such asFabric,Forge,NeoForgeandQuilt. To start such versions,
you can prefix the version with eitherfabric:,forge:,neoforge:orquilt:(orvanilla:to explicitly choose a vanilla version).
Depending on the mod loader, the version you put after the colon is different:For Fabric and Quilt, you can directly specify the vanilla version, optionally followed
by:<loader_version>.For Forge and NeoForge, you can put either a vanilla game version, optionally followed
by-<loader_version>. Forge also supports-latestand-recommended, but NeoForge
will always take the latest loader.You can search for versions using thesearch command.# Start latest releaseportablemcstart
portablemcstartrelease# Start latest snapshotportablemcstartsnapshot# Start 1.20.1portablemcstart1.20.1# Start latest Fabric/Quilt/Forge versionportablemcstartfabric:
portablemcstartquilt:
portablemcstartforge:
portablemcstartneoforge:# Start Fabric for 1.20.1portablemcstartfabric:1.20.1# Start Fabric for 1.20.1 with loader 0.11.2portablemcstartfabric:1.20.1:0.11.2# Start latest or recommended Forge for 1.20.1portablemcstartforge:1.20.1-latest
portablemcstartforge:1.20.1-recommended# Start Forge for 1.20.1 with loader 46.0.14portablemcstartforge:1.20-46.0.14# Start NeoForge for 1.20.1portablemcstartneoforge:1.20.1AuthenticationOnline mode is supported by this launcher, use the-l <email_or_username>(--login)
argument to log into your account(login with a username is deprecated by Mojang).
If your session is not cached or no longer valid, the launcher will ask for the
password or open the Microsoft connection page.By default, this will authenticate you using the Microsoft authentication services,
although you can change that using the--auth-serviceargument, for example withyggdrasilif you need to log into an old Mojang account (being phased out by Mojang).If you want to be asked for password on each authentication, you can use-t(--temp-login). This has no effect if the session is already cached before that.You can also use--auth-anonymizein order to hide most of your email when printing
it to the terminal. For example,foo.bar@gmail.comwill becomef*****r@g***l.com,
this is useful to avoid leaking it when recording or streaming.
However, if you use this, make sure that you either use an alias or a variable with the-largument, for exemple-l $PMC_LOGIN.Check belowfor more information about authentication
sessions.Username and UUIDIf you need fake offline accounts you can use-u <username>(--username) to define the
username and/or-i <uuid>(--uuid) to define your player'sUUID.If you omit the UUID, a random one is chosen. If you omit the username, the first 8
characters of the UUID are used for it.These two arguments are overwritten by the-l(--login) argument.Custom JVMThe launcher uses Java Virtual Machine to run the game, by default the launcher downloads
and uses the official JVM distributed by Mojang which is compatible with the game version.
The JVM is installed in a sub-directory calledjvminside the main directory.
You can change it by providing a path to thejavabinary with the--jvm <path_to/bin/java>argument. By default, the launcher starts the JVM with default
arguments, these are the following and are the same as the Mojang launcher:-Xmx2G -XX:+UnlockExperimentalVMOptions -XX:+UseG1GC -XX:G1NewSizePercent=20 -XX:G1ReservePercent=20 -XX:MaxGCPauseMillis=50 -XX:G1HeapRegionSize=32MYou can change these arguments using the--jvm-args=<args>,please always quote your
set of arguments, this set must be one argument for PMC. For exampleportablemc start "--jvm-args=-Xmx2G -XX:+UnlockExperimentalVMOptions".Server auto-connectSince Minecraft 1.6 we can start the game and automatically connect to a server.
To do so you can use-s <addr>(--server) for the server address
(e.g.mc.hypixel.net) and the-p(--server-port) to specify the port,
defaults to 25565.Modern releases use the quick play arguments rather than arguments specified above, the
behavior remains the same, singleplayer and realm are not yet supported by the launcher.LWJGL version and ARM supportWith--lwjgl VERSIONyou can update the LWJGL version used when starting the game. This
can be used to support ARM architectures, but this may only work with modern versions
which are already using LWJGL 3. This argument works by dynamically rewriting the
version's metadata, the new metadata is dumped in the version directory.Using these versions on ARM is unstable and can show you an error withGLXBadFBConfig,
in such cases you should export the following environment variableexport MESA_GL_VERSION_OVERRIDE=4.5(more info here).In case with the above you still get anerror: GLSL 1.50 is not supportedyou may also
tryexport MESA_GLSL_VERSION_OVERRIDE=150.Fix unsupported systemsSome Mojang-provided natives (.so, .dll, .dylib) might not be compatible with your system.
To mitigate that, the launcher provides two arguments,--exclude-liband--include-binthat can be provided multiples times each.With--exclude-lib <artifact>[:[<version>][:<classifier>]]you can exclude libraries
(.jar) from the game's classpath (and so of the downloads). If a classifier is given, it
will match libs' classifiers that starts with itself, for examplelwjgl-glfw::nativeswill match the librarylwjgl-glfw:3.3.1:natives-windows-x86.With--include-bin <bin-file>you can dynamically include binary natives (.so, .dll,
.dylib) to the runtime's bin directory (usually under.minecraft/bin/<uuid>).
The binary will be symlinked into the directory, or copied if not possible (mostly on
Windows). For shared objects files (.so) that contains version numbers in the filename,
these are discarded in the bin directory, for example/lib/libglfw.so.3 -> .minecraft/bin/<uuid>/libglfw.so.These arguments can be used together to fix various issues (e.g. wrong libc being linked
by the LWJGL-provided natives).[!NOTE]
Note that these arguments are compatible with, and executed after the--lwjglargument. You must however ensure that excluded lib and included binaries are
compatible.MiscellaneousWith--dry, the start command does not start the game, but simply installs it.With--demoyou can enable thedemo modeof the game.With--resolution <width>x<height>you can change the resolution of the game window.The two arguments--disable-mp(mp: multiplayer) and--disable-chatcan respectively
disable the multiplayer button and the in-game chat(since 1.16).Search for versionsTheportablemc search [-k <kind>] [version]command is used to search for versions.
By default, this command will search for official Mojang versions available to download,
you can instead search for many kinds of versions using the-k(--kind) arguments:local, show all installed versions.forge, show all recommended and latest Forge loader versions(only 1.5.2 and
onward can be started).fabric, show all available Fabric loader versions.quilt, show all available Quilt loader versions.The search string is optional, if not specified no filter is applied on the table shown.Authentication sessionsTwo subcommands allow you to store or logout of sessions:portablemc login|logout <email_or_username>.
These subcommands don't prevent you from using the-l(--login) argument when starting
the game, these are just here to manage the session storage.By default, this will authenticate you using the Microsoft authentication services,
you can change that using--auth-serviceargument, for example withyggdrasilif
you need to log into an old Mojang account (being phased out by Mojang).Your password is not saved!Only tokens are saved(the official launcher also does
that)in the fileportablemc_auth.jsonin the working directory.Shell completionThe launcher can generate shell completions scripts for Bash and Zsh shells through theportablemc show completion {bash,zsh}command. If you need precise explanation on how
to install the completions, read this command's help message.This command needs to be
re-run for every new version of the launcher, you're not affected if you directly eval
the result.Note that Zsh completion scripts can be used both as an auto-load script and as
evaluated one.Offline supportThis launcher can be used without internet access under certain conditions. Launching
versions is possible if all required resources are locally installed, it is also possible
to search for versions(only Mojang, not Forge/Fabric/Quilt)if the version manifest
is locally cached, this can be forced by just running the search or start commands with
internet access, you can also copy the relevant files from an online computer to your
offline one.Authentication commands and arguments are however not supported while offline.An example use case has been documented in issue#178.Certifi supportThe launcher supportscertifiwhen installed.
This package providesMozilla’s carefully curated collection of Root Certificates for
validating the trustworthiness of SSL certificates while verifying the identity of TLS
hosts.This can be useful if you encounter certificates errors while logging into your account
or downloading other things. Problems can arise because Python depends by default on your
system to provide these root certificates, so if your system is not up to date, it may be
necessary to installcertifi.ContributeSetup environmentConda (or Miniconda) is recommended for easy development together with Poetry.
If you want to try you can use the following commands:#YoucanuseanyversionofPythonherefrom3.7totest#compatibilityofthelauncher.conda create -n pmc python=3.11 pip#Thislineisoptionalifyoudon'thaveanyusersite-packages#inyourhostinstallation,ifnotitallowstoisolatepip.#Thisisusefultoavoidconflictswithpackagesinstalled#outsideoftheenvironment.conda env config vars set PYTHONNOUSERSITE=1 -n pmcOnce you have a conda environment, you can install the development version locally in it:#Assumeweareintheproject'sdirectory.#First,weneedtoactivatetheenvironment.conda activate pmc#Ifpoetryisn'tinstalled,oroutdated#(minimumversiontestedis1.5.0).pip install poetry --upgrade#Thenyoucaninstalltheportablemcpackagelocally.poetry install#Now,youcantestthedevelopmentversionofthelauncher.portablemc show aboutYou can call this development version from everywhere using:conda run -n pmc portablemcContributorsThis 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,JamiKettunenMisileLaboratoryandGooseDeveloper.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!SponsorsI'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 onGitHub SponsorsorKo-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 toErwan Oranduser10072023githubfor their donations!