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.
We have tested direct installation on Ubuntu 20.04 and MacOS. Other systems may be supported but not guaranteed. We welcome community contributions!
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
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
Pick up the path similar to
/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home and 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
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
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 .
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.
Note that if you are on a headless machine, you should prepend either
xvfb-run python minedojo/scripts/validate_install.py MINEDOJO_HEADLESS=1 python minedojo/scripts/validate_install.py
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
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.
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,
An xvfb session autotimatically starts when the continaer gets launched. So there is no need to prepend
xvfb-run to run with software renderer.
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.