> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ubuntu Installation

> Install and run a Quai Network GPU miner on Ubuntu.

<Warning>
  Running a GPU miner on an Ubuntu based Virtual Machine may not work properly. This includes most VMs that run on top of Windows or WSL2.
</Warning>

## Introduction

Here, we'll be installing [quai-gpu-miner](https://github.com/dominant-strategies/quai-gpu-miner), the implementation of a Quai Network ProgPOW miner. This tutorial will focus on installing and running quai-gpu-miner on [Ubuntu](https://ubuntu.com/), an enterprise and open source Linux distribution.

### Requirements

In order to run the quai-gpu-miner on Ubuntu and mine valid blocks, you'll need the following:

<CardGroup cols={3}>
  <Card title="Synced go-quai node" href="/guides/client/node" icon="computer" />

  <Card title="Configured Stratum proxy" href="/guides/client/stratum" icon="router" />

  <Card title="Ubuntu machine" icon="ubuntu" />

  <Card title="AMD or NVIDIA GPU" icon="microchip" />

  <Card title="4GB+ of RAM" icon="usb-drive" />
</CardGroup>

## Environment Setup

### Ubuntu

For this tutorial, you'll need an Ubuntu machine. Instructions on how to download and install Ubuntu on your machine can be found on the [Ubuntu installation instructions](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview).

<Note>
  The quai-gpu-miner is default configured to be compiled on Ubuntu v20.04. If you're using other versions of Ubuntu, you may need to change
  the CUDA toolkit version in the installation script.
</Note>

### Miner Installation

The [quai-gpu-miner](https://github.com/dominant-strategies/quai-gpu-miner) repository contains a [automated script](https://github.com/dominant-strategies/quai-gpu-miner/blob/main/deploy_miner.sh) that can be used to compile and build the miner. The `deploy_miner.sh` script will install the following build dependencies and build the latest version of the miner:

* git
* cmake
* build-essential
* mesa-common-dev
* [Nvidia CUDA Toolkit v12.6](https://developer.nvidia.com/cuda-12-6-0-download-archive)

To download the script, run the following command:

```bash theme={null}
wget https://raw.githubusercontent.com/dominant-strategies/quai-gpu-miner/refs/heads/main/deploy_miner.sh
```

Once the download is complete, make the `deploy_miner.sh` file executable:

```bash theme={null}
sudo chmod +x deploy_miner.sh
```

<Tip>
  This script installs the CUDA keyring version for Ubuntu v20.04. If you're using other versions of Ubuntu, you may need to edit the CUDA
  keyring version downloaded in the script. This can be done by changing the `/ubuntu2004/` to the version of Ubuntu you're using in the
  keyring download link.
</Tip>

Run the script with the following command:

```bash theme={null}
sudo ./deploy_miner.sh
```

<Warning>
  Running this command will compiling and build the miner. This process may take a while to complete, and requires around 10gb of RAM.
</Warning>

This will create an `output` directory with two built binaries in it: `quai-gpu-miner-amd` and `quai-gpu-miner-nvidia`. For the card type you have, run the following command to make the binary executable:

<Tabs>
  <Tab title="NVIDIA">
    ```bash theme={null}
    chmod +x output/quai-gpu-miner-nvidia
    ```
  </Tab>

  <Tab title="AMD">
    ```bash theme={null}
    chmod +x output/quai-gpu-miner-amd
    ```
  </Tab>
</Tabs>

### Dependencies and Drivers

Now that we've installed and built the miner, we need to make sure our system and drivers are up to date.

```bash theme={null}
sudo apt update && sudo apt upgrade -y
```

Then, install NVIDIA drivers:

```bash theme={null}
sudo apt install cuda-drivers
```

To apply the NVIDIA driver updates, restart your machine with:

```bash theme={null}
sudo reboot
```

## Configure And Run

To run the miner, you'll need a Stratum proxy to connect to. Visit the [quai-stratum-proxy](/guides/client/stratum) docs for information on how to install and configure it. The proxy configuration will determine which shard your gpu-miner is running on and the address payouts are awarded to.

First, you'll need to obtain the IP Address and port your proxy is running on from the Stratum proxy logs. The default port is `3333`.

<Note>
  If your miner and proxy are on the same machine, the `PROXYIPADDRESS` will be `localhost`. If your miner and proxy are not on the same
  machine, you may need to port forward the proxy port.
</Note>

Once you've obtained the IP Address and port, run the miner with the following command, making sure to replace `PROXYIPADDRESS` with the IP Address and `STRATUMPORT` with the port your proxy is running on:

<Tabs>
  <Tab title="NVIDIA">
    ```bash theme={null}
    ./output/quai-gpu-miner-nvidia -U -P stratum://PROXYIPADDRESS:STRATUMPORT
    ```
  </Tab>

  <Tab title="AMD">
    ```bash theme={null}
    ./output/quai-gpu-miner-amd -G -P stratum://PROXYIPADDRESS:STRATUMPORT
    ```
  </Tab>
</Tabs>

The quai-gpu-miner should now be running and outputting logs to the terminal.

<Warning>
  Do not start the miner before confirming your node has fully synced. Mining while your node is not synced will result in the mining of
  **invalid blocks** and **wasted hash**.
</Warning>

### Stop

To stop the miner, simple use **CTRL+C** to kill the terminal process. Once logs are no longer being outputted to the terminal, the miner has stopped.