# Linux

## Overview

Use this guide to install and set up BlockAssist on Linux systems, with **Ubuntu 22.04 LTS** as the recommended distribution. It includes environment configuration, dependency installation, and verification steps to prepare for running and training BlockAssist locally.

### Prerequisites

* Ubuntu 22.04 LTS or compatible Linux distribution
* At least 12 GB RAM (32 GB recommended for training stability)
* Git installed
* Hugging Face account with a [Write-access API token](https://docs.gensyn.ai/testnet/blockassist/hugging-face-guide)
* Gensyn Testnet account

{% hint style="success" %}
If you don't have a Testnet account, don't worry--you'll be prompted to create it automatically on your first log-in attempt.
{% endhint %}

### Dependencies

* **Core:** Python 3.10.x (via pyenv) & Java 1.8.0\_152 (OpenJDK 8)
* **Optional:** CUDA/cuDNN for Nvidia GPU acceleration
* **Package Manager:** APT (default for Ubuntu)

### Installation Steps

#### Step 1 — Clone the Repository

Clone the BlockAssist repository and navigate into it.

```bash
git clone https://github.com/gensyn-ai/blockassist.git  
cd blockassist
```

#### Step 2 — Install Java 1.8.0\_152

Run the setup script included with the repository. This installs and configures Java 8, which is required for the underlying Minecraft environment.

```bash
./setup.sh
```

Verify Java installation by running:

```bash
java -version
```

You should see a version number beginning with 1.8.0\_152.

#### Step 3 — Install pyenv

Install pyenv to manage your Python environment.

```bash
curl -fsSL https://pyenv.run | bash
```

Follow the instructions provided by pyenv to add it to your shell configuration file (for example, .bashrc or .zshrc).

Then initialize pyenv:

```bash
export PYENV_ROOT="$HOME/.pyenv"  
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"  
eval "$(pyenv init --path)"  
eval "$(pyenv init -)"  
source ~/.bashrc
```

#### Step 4 — Install Core Dependencies

Install system-level dependencies required for building and compiling Python.

```bash
sudo apt update  
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
libsqlite3-dev curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev zip unzip
```

Once complete, use `pyenv` to install Python 3.10 and set it globally.

```bash
pyenv install 3.10.13  
pyenv global 3.10.13
```

Confirm that Python was installed correctly using the following command: 

```bash
python --version
```

#### Step 5 — Install Python Packages

Install required Python libraries for BlockAssist.

```bash
pip install psutil readchar rich
```

#### Step 6 — Verify Installation

At this point, your environment is ready. Verify that Java, Python, and pyenv are properly configured:

```bash
java -version  
python --version  
pyenv versions
```

{% hint style="info" %}
Each should return a valid version number with no errors.
{% endhint %}

***

### Platform-Specific Notes

* Use Ubuntu 22.04 LTS for maximum compatibility. Other distributions may require slight package name adjustments.
* If you are running Ubuntu on ARM hardware (such as Raspberry Pi or ARM-based servers), ensure that you install the ARM-compatible version of OpenJDK 8.
* For Nvidia GPU users, installing CUDA and cuDNN is *optional* but can accelerate model training.

### Authentication

Once installation is complete, you will authenticate when running BlockAssist for the first time.

* You’ll be prompted for your Hugging Face Write-access API token. Follow the instructions provided in the [Hugging Face Guide](https://docs.gensyn.ai/testnet/blockassist/hugging-face-guide) to generate one if you haven’t already.
* A browser window will open for Gensyn Testnet login. If you have logged in previously, this step will be skipped automatically.

### Troubleshooting

Below are some quick fixes for some common installation issues. 

* If `pyenv: command not found`, reinitialize `pyenv` using the following command:

```bash
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
```

* If Java fails to install via `setup.sh`, manually install OpenJDK 8:

```bash
sudo apt install -y openjdk-8-jdk
```

* If Python installation fails, ensure all required build dependencies are installed (`build-essential`, `zlib1g-dev`, `libssl-dev`, etc.).

For any missing Python packages, `rerun pip install -e .` from inside the BlockAssist folder.

{% hint style="success" %}
If you need additional support, you can [open a ticket](https://github.com/gensyn-ai/blockassist/issues) or [visit our Discord.](https://discord.com/invite/gensyn) 
{% endhint %}