Installation

Welcome to MineDojo’s doc page! We are glad that you are here to join us on the quest for open-ended, generally capable embodied agent. MineDojo is a Python based library for Minecraft simulation, massively multi-task benchmarking suite, and internet-scale database access.
In this section, we will cover 2 different methods to install MineDojo: direct installation or through Docker.

Direct Install

We have tested direct installation on Ubuntu 20.04 and MacOS. Other systems may be supported but not guaranteed. We welcome community contributions!

Prerequisites

On Ubuntu 20.04

Java JDK 8 is required to support the backend of MineDojo. To install JDK 8 on Ubuntu 20.04, you can run the following command:

apt update -y && apt install -y software-properties-common && \
    add-apt-repository ppa:openjdk-r/ppa && apt update -y && \
    apt install -y openjdk-8-jdk

After installing Java JDK 8, in case your Ubuntu comes with pre-installed Java, you may need to run the following code to switch default Java version:

sudo update-alternatives --config java

Note that if your machine is headless, for example a VM on Google Cloud Platform, you need to use a software renderer such as xvfb such that our codebase can work properly. To install xvfb and other dependencies, run

sudo apt install xvfb xserver-xephyr vnc4server python-opengl ffmpeg

To run with xvfb, you can either prepend xvfb-run to commands running Python scripts, or set environment variable MINEDOJO_HEADLESS=1. The code block below demonstrates these two options.

xvfb-run python path/to/minedojo/python/scripts.py

MINEDOJO_HEADLESS=1 python path/to/minedojo/python/scripts.py

On MacOS

We follow the instruction to install Java JDK 8 on MacOS. Concretely, run the following code to install Eclipse Temurin 8.

brew tap homebrew/cask-versions
brew install --cask temurin8

After installing Eclipse Temurin 8, you may need to change the default Java. First run the code below to list all installed Java

/usr/libexec/java_home -V

Pick up the path similar to /Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home and run

export JAVA_HOME=path/to/eclipse/temurin8

Run java -version to verify Java version, you should see outputs similar to

openjdk version "1.8.0_322"
OpenJDK Runtime Environment (Temurin)(build 1.8.0_322-b06)
OpenJDK 64-Bit Server VM (Temurin)(build 25.322-b06, mixed mode)

Make sure to run MineDojo in the same terminal with correct JAVA_HOME exported.

Python Environment

Python ≥ 3.9 is required. We highly recommend that you create a new virtualenv. The code block below demonstrates how to create a Conda env named minedojo with Python3.9 and then activate it.

conda create -y -n minedojo python=3.9
conda activate minedojo

Install MineDojo

We host the stable version of MineDojo on PyPI, which makes installation extremely simple:

pip install minedojo

To install the latest main branch, clone our Github repo and run install:

git clone https://github.com/MineDojo/MineDojo && cd MineDojo
pip install -e .

Verify Installation

You can run the script below to verify the installation. It takes a while to compile the Java code for the first time. After that you should see a Minecraft window pop up, with the same gaming interface that human players receive. You should see the output [INFO] Installation Success if everything goes well.

python minedojo/scripts/validate_install.py

Note that if you are on a headless machine, you should prepend either xvfb-run or MINEDOJO_HEADLESS=1.

xvfb-run python minedojo/scripts/validate_install.py

MINEDOJO_HEADLESS=1 python minedojo/scripts/validate_install.py

Docker Image

We provide pre-built docker image for easier installation. Our docker image also supports GPU-accelerated simulation on headless machines such as training nodes on a server. To pull the image, simply run

docker pull minedojo/minedojo:latest

To start a docker container in detached mode, run

docker run --gpus all -it -d -p 8080:8080 minedojo/minedojo:latest tail -f /dev/null

You can then interact with the running container through

docker exec -it <running_container_id> /bin/bash

Usage

To run MineDojo simulation with GPU accelerated rendering (i.e., higher throughput), prepend commands with vglrun and make sure not running with sudo. For example,

vglrun python3 sample_script.py

You should then see GPU usage caused by running Java client.

Note

To be able to leverage GPU acceleration, the host machine should have NVIDIA GPU driver installed with version of at least 450.80.02.

Our image also supports running the simulation without GPU acceleration. To do this, simply run without prepending vglrun. For example,

python3 sample_script.py

Note

An xvfb session autotimatically starts when the continaer gets launched. So there is no need to prepend xvfb-run to run with software renderer.

Acknowledgement

We build upon this docker image from this repo. We sincerely thank Xiaojian Ma for his assistance when we devloped this docker image. You can find our raw Dockerfile in this repo.