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

Run a Local Bittensor Blockchain Instance

This tutorial will guide the user through running a local instance of Subtensor, Bittensor's L1 blockchain. Running a local instance of the Subtensor blockchain is a great way to test changes and explore the network in a safe and isolated environment.

Running a local subtensor instance​

This section outlines steps for running a local instance of the Subtensor blockchain. There are two supported methods:

  • Using a prebuilt Docker image
  • Running a local build from source

Both approaches enable isolated testing, development, and debugging without requiring a connection to the mainnet. Choose the method that best fits your workflow.

Docker is the easiest way to set up a local Bittensor blockchain instance. It only takes a few minutes to get up and running with Docker.

The steps in this guide assume that you are running the command from the machine you intend to host from.

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.

1. Pull the Docker image​

You can pull the official subtensor Docker image used to create the local blockchain instance from the GitHub Container Repository. To do this, run the following command in your terminal:

docker pull ghcr.io/opentensor/subtensor-localnet:devnet-ready

This command downloads the subtensor-localnet Docker image, making it available on your device.

2. Run the container​

Subtensor can either be run in fast blocks mode, which has advantages for development and testing purposes, or non-fast blocks. Below are examples of how to run the container using each mode:

  • Fast blocks: Fast block mode reduces block processing time to 250ms per block, enabling rapid chain progression. It allows faster feedback cycles for operations such as staking, subnet creation, and registration, making them ideal for local testing scenarios. To run the container in fast block mode, run the following command in your terminal:

    docker run --rm --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready

  • Non-fast blocks: Non-fast block mode uses the default 12-second block time, aligning with subtensor block intervals. While this mode utilizes the default block processing time, it also incorporates some enhancements—for example, subnets become eligible to start one minute after creation. To run the container in non-fast block mode, run the following command in your terminal:

    docker run --rm --name test_local_chain_ -p 9944:9944 -p 9945:9945 ghcr.io/opentensor/subtensor-localnet:devnet-ready False

3. Verify your setup​

You can verify your local blockchain instance by checking the list of subnets available on your local blockchain. To do this, run the following command in the terminal:

btcli subnet list --network ws://127.0.0.1:9944

If the local blockchain is running correctly, you should see the following output:

                                                           Subnets
                                                         Network: custom


        ┃        ┃ Price       ┃ Market Cap  ┃              ┃                        ┃               ┃              ┃
 Netuid ┃ Name   ┃ (τ_in/α_in) ┃ (α * Price) ┃ Emission (τ) ┃ P (τ_in, α_in)         ┃ Stake (α_out) ┃ Supply (α)   ┃ Tempo (k/n)
━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━
   0    │ τ root │ 1.0000 τ/Τ  │ τ 0.00      │ τ 0.0000     │ -, -                   │ Τ 0.00        │ 0.00 Τ /21M  │ -/-
   1    │ α apex │ 1.0000 τ/α  │ τ 11.00     │ τ 0.0000     │ τ 10.00, 10.00 α       │ 1.00 α        │ 11.00 α /21M │ 77/100
────────┼────────┼─────────────┼─────────────┼──────────────┼────────────────────────┼───────────────┼──────────────┼─────────────
   2    │        │ τ 1.0       │             │ τ 0.0        │ τ 10.00/175.00 (5.71%) │               │              │

Next steps​

Once your local chain is running, the next step is to provision wallets for local deployment. This includes creating hotkeys and coldkeys, funding wallets, and preparing accounts for testing or development tasks. For more information, see Provision Wallets for Local Development.