Skip to main content
SUBMIT A PRSUBMIT AN ISSUElast edit: Jul 21, 2025

Using Docker

To run a subtensor node with Docker, follow the below steps.

Not tested on cloud

We have not tested subtensor node installation scripts on any cloud service. In addition, if you are using Runpod cloud service, then note that this service is already containerized. Hence, the only option available to you for Runpod is to install a subtensor node by compiling from source. Note that we have not tested any subtensor installation steps on Runpod.

If you are already running a subtensor node using Docker, then go directly to Step 5 Prepare to Run . The below steps 1 through 4 are for first time users only.

Prerequisites​

Before you begin, make sure you have installed the following on your machine:

The Bittensor SDK and Bittensor CLI are required to interact with the local blockchain instance.

Step 1: Clone the subtensor repo​

Clone the subtensor repository and navigate into the Subtensor directory:

git clone https://github.com/opentensor/subtensor.git
cd subtensor
Always Pull the Latest Changes

Before running the subtensor node, always ensure that you're working with the latest version of the repository. To do this, run the following command in the subtensor directory to fetch and merge the most recent updates:

git pull

Step 2: Clean Docker environment​

Next, stop any currently running Docker containers and clean up the Docker environment using the following command:

docker compose down --volumes && docker system prune -a --volumes -f

Linux post-installation steps for Docker Engine

Please follow Docker's official documentation to perform standard Linux post-installation steps for Docker Engine

Adding a user to the docker group is only necessary on Linux, where sudo privileges are required to run Docker commands. It is unnecessary on macOS.

Step 3: Run the subtensor node​

Now you can run the subtensor nodes for either mainchain or testchain using any of available options.

Using lite nodes​

A lite node which primarily syncs with the only blocks that have been finalized, and not the entire blockchain. Run a lite node using the command corresponding to your target chain:

To run a lite node connected to the Bittensor mainchain, run the following command:

./scripts/run/subtensor.sh -e docker --network mainnet --node-type lite

The command pulls the Subtensor Docker image and starts the container.

Docker Resource Allocation

Ensure Docker is configured with sufficient CPU and memory resources to meet the system requirements for running a subtensor node. Inadequate allocation may prevent the node from starting correctly.

We recommend allocating at least 20 GB of RAM. You can adjust these settings in Docker Desktop under Settings > Resources.

Using archive nodes​

An archive node downloads and validates all the Bittensor blockchain blocks from inception up to the most recent block. Run an archive node using the command corresponding to your target chain:

To run an archive node connected to the Bittensor mainchain, run the following command:

./scripts/run/subtensor.sh -e docker --network mainnet --node-type archive

The command pulls the Subtensor Docker image and starts the container.