Installation

For the first step of our journey, let’s install MCDR

Note

We assume you have some really basic knowledge of Python and pip.

If you have not, Google is your friend

Requirements

Python version PyPI version

MCDR is written and runs in Python 3. Make sure you have Python 3.8 or later, with pip installed

The detailed Python version requirements are as shown in the table below

MCDR version

Python requirement

< 2.10

>= 3.6

>= 2.10

>= 3.8

>= 2.15 (future version)

>= 3.9

Wait a second

In some tutorials, you may learn to use MCDR by downloading a zip from Github and extracting it

However, that’s not the correct way to install MCDR - Those tutorials are outdated. Since the release of version 1.0 in early 2021, MCDR has no longer used source code installation

Caution

DO NOT download the source files of MCDR and execute them directly, unless you’re a developer of MCDR and you know what you are doing

Install using pip

MCDR is available in PyPI, it’s reasonably to be installed by:

pip install mcdreforged

pip3 install mcdreforged

And upgraded by:

pip install mcdreforged -U

pip3 install mcdreforged -U

Verify the installation with:

mcdreforged
MCDReforged v2.13.2

For users in China, if you encounter slow downloads or network issues while using pip to install packages, you can refer to the Accelerate the installation section below to resolve these issues

Externally managed environment

If you’re using Windows, the command above should work fine, and MCDR will be installed to the global environment - you may ignore this section

For Linux and Mac OS, it’s not recommended to install MCDR system-wide (with root), because it can cause conflicts with other Python packages and affect system dependencies

System-wide installation also makes version management difficult and requires administrator privileges, increasing security risks

System-wide installation may even result in an externally-managed-environment error

An animated demo on the externally-managed-environment error

See PEP 668 for the detailed specification

It’s safer to keep the installation isolated. As workarounds, there’re multiple options for you. In conclusion:

Method

Pros

Cons

pip

Native, always available

Not isolated, may affect global packages with root privileges

pipx

Simplest

3rd party, different command set

venv

Native support

Requires manual environment activation

docker

Reliable across environments

More dependencies and disk space, convoluted learning path

system package

-

Same as pip, not recommended

Using pipx

It may be the simplest solution for most users, but it requires using the third-party tool pipx, which is designed for installing and running Python applications in isolated environments

To install pipx, please refer to its official documentation

Then you can install MCDR using pipx:

pipx install mcdreforged

When a new version of MCDR is available, you can upgrade MCDR by:

pipx upgrade mcdreforged

Note

In this way, MCDR will be installed in an isolated environment managed by pipx. To install Python packages into this environment, instead of using pip install <package_name>, you should use:

  • pipx inject mcdreforged <package_name>, e.g. pipx inject mcdreforged requests

  • or pipx inject mcdreforged -r requirements.txt

More conveniently, you can use the !!MCDR plg command to install plugins with their dependencies

Using virtual environment

For the most native, but more complicated option, you can create a virtual environment and install MCDR in it

Create a virtual environment by:

python3 -m venv <venv directory>

venv for example:

python3 -m venv venv

Activate it by:

Platform

Shell

Command to activate virtual environment

POSIX

bash/zsh

source venv/bin/activate

fish

source venv/bin/activate.fish

csh/tcsh

source venv/bin/activate.csh

PowerShell

venv/bin/Activate.ps1

Windows

cmd.exe

venv\Scripts\activate.bat

PowerShell

venv\Scripts\Activate.ps1

See also

Python Doc: How venvs work

After activating the virtual environment, a (venv) prefix should appear in your terminal environment

Then, install MCDR using pip:

pip install mcdreforged

When a new version of MCDR is available, you can upgrade MCDR by:

pip install mcdreforged -U

An animated demo with bash:


Note

In this way, you must activate the virtual environment every time you want to use MCDR, or install packages for MCDR plugins

For more information, see venv in the Python Doc

Using Docker

MCDR also provides Docker images as an option. See Docker for more details

In addition to the basic MCDR image, MCDR also provides image variants pre-installed with additional Python packages and OpenJDK.

Compared to the two methods above, Docker has a more convoluted learning path, but is more convenient for some advanced usages

System package manager

You may find MCDR in some system package repositories, AUR for example. However, it’s definitely not recommended to use a system package manager to install MCDR. Not only does it have all the same problems as system-wide pip installation, but it’s also hard to manage the dependencies of MCDR plugins

Accelerate the installation

For users in China, you may use a PyPI mirror, Tsinghua University TUNA mirror for example, to accelerate pip and pipx

To use the PyPI mirror, add -i <index-url> to the commands:

pipx install -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged
pipx upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcdreforged -U

Or simply set a global index-url by:

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple