Migrating from v9/v10

Bittensor 11 replaces two packages — the bittensor SDK (v10.x) and the separate bittensor-cli (v9.x, the old btcli) — with one package that contains both. The API is not a rename of the old one: the Subtensor class and its ~165 methods are gone, replaced by a small Client with typed reads and a catalog of intents executed through one plan/execute pipeline. This page maps every commonly scripted old call and CLI command to its v11 equivalent.

If you are an LLM migrating a user's scripts, follow this procedure:

1. Read this entire page — the tables are exact, not illustrative.
2. Apply the SDK mappings and CLI mappings mechanically; where a row says "no direct equivalent", use the listed escape hatch.
3. Watch the semantic traps in Money, Weights and take, and Results and errors — these change behavior, not just names.
4. Verify against the live catalogs rather than guessing: sub.intents.list_tools() and sub.reads.list_reads() in Python, btcli tools and btcli query --help on the CLI, or the generated references under Transactions and Queries.
5. Preview every rewritten mutation with client.plan(...) or --dry-run before submitting anything.

Packages and install

uv pip install bittensor          # library + btcli, one package

The [cli] and [evm] extras still parse (bittensor[cli] installs fine) but are empty — everything is in the base install now.

Remove bittensor-cli and bittensor_wallet from your requirements; both are superseded. Wallets on disk are keyfile-compatible — nothing to convert (see Wallets).

Upgrading an existing environment

Order matters in an environment that already has the old stack, because bittensor-cli 9.x and bittensor 11.x both own the btcli command:

pip uninstall -y bittensor-cli bittensor-wallet
pip install -U bittensor

If you upgraded first and uninstalled bittensor-cli after, pip deletes the btcli script (it is still listed in the old package's file manifest). Nothing is lost — reinstate it with:

pip install --force-reinstall --no-deps bittensor

While a stale bittensor-cli is still installed, the v11 btcli prints a warning with this fix on every run.

Two version pitfalls that fail silently:

• Python 3.14: v10 allowed it, v11 supports 3.10–3.13. On a 3.14 interpreter pip install -U bittensor quietly keeps 10.x (pip picks the newest release whose requires-python matches). If btcli --version still says 9.x/10.x after upgrading, check python --version first.
• Pinned requirements: anything pinning bittensor<11 or bittensor~=10 keeps working against v10 untouched — the new package changes nothing until you move the pin.

Platform support: wheels ship for Linux (x86_64, aarch64) and macOS (Apple Silicon and Intel), Python 3.10–3.13 — the same coverage as the old stack. Windows is unsupported natively (as before); use WSL. On any other platform pip falls back to a source build, which requires a Rust toolchain.

The model change in one example

Old (v10):

import bittensor as bt

subtensor = bt.Subtensor(network="finney")
wallet = bt.Wallet(name="my_coldkey", hotkey="my_hotkey")

balance = subtensor.get_balance("5F...")
response = subtensor.add_stake(
    wallet, netuid=1, hotkey_ss58="5F...validator", amount=bt.tao(10),
)
if not response.success:
    print(response.message)

New (v11):

import asyncio
import bittensor as sub
from bittensor.wallet import Wallet

async def main():
    wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
    async with sub.Client("finney") as client:
        balance = await client.balances.get("5F...")
        result = await client.execute(
            sub.AddStake(hotkey_ss58="5F...validator", netuid=1, amount_tao=10),
            wallet,
        )
        if not result.success:
            print(result.error.code, result.error.remediation)

asyncio.run(main())

The three structural changes:

1. One client, no method zoo. Subtensor / AsyncSubtensor become sub.Client (async) or sub.SyncClient (blocking, same surface). Every read is a typed method on a category namespace (client.subnets, client.staking, client.delegation, client.prices, ... — with autocomplete and signature help), is also dispatchable by name (client.read("uid", hotkey_ss58=..., netuid=...)), and anything else is reachable through generic accessors (client.query(sub.storage...)). See The client.
2. Transactions are intents. Every mutation is a small dataclass (sub.Transfer, sub.AddStake, sub.SetWeights, ...) executed through client.plan(intent, wallet) / client.execute(intent, wallet). See The transaction model.
3. Results are data. ExtrinsicResponse becomes ExtrinsicResult with a classified error.code and a remediation hint instead of prose.

Connecting

Network names finney, test, archive, local resolve to the same endpoints as before, and any ws:// / wss:// URL is accepted directly. The extra v9-CLI aliases (dev, rao, latent-lite) are gone — pass the URL.

Every v10 read took block=. In v11, namespace methods still accept block=, and for multi-read consistency pin a snapshot:

snap = await client.at(block)          # Snapshot: same read surface, one block
bal = await snap.balances.get("5F...")

Environment variables and configuration

The old argparse machinery — bt.Config, Subtensor.add_args, Wallet.add_args, --subtensor.network, --wallet.name flags parsed inside the SDK — is gone entirely. Scripts own their own argument parsing; the SDK reads nothing from sys.argv.

bt.logging is gone. The SDK logs under the bittensor.* namespace via the standard library and configures no handlers:

import logging
logging.getLogger("bittensor").setLevel(logging.DEBUG)

Reading chain state

General rules: every named read below is a typed method on its namespace (client.staking.stake_for_coldkey(...)) and equally dispatchable by name (client.read("stake_for_coldkey", ...)); both take the same ..._ss58 parameter names the old methods used. Results that used to be raw u16/u64 integers come back normalized (weights and bonds as 0..1 floats, balances as Balance). Anything without a named read is reachable through the generic accessors — client.query(sub.storage.Pallet.Item, [params]), client.query_map(...), client.constant(sub.constants...), client.runtime(sub.runtime_api...) — which cover the entire runtime surface, replacing query_subtensor, query_module, query_map, query_map_subtensor, query_constant, query_runtime_api, and state_call.

Balances and stake

Subnets and hyperparameters

Neurons, registration, delegates

Chain, blocks, and the rest

The metagraph

subtensor.metagraph(netuid) returned an object of parallel NumPy arrays (S, W, B, I, uids, hotkeys, axons, ...) with sync(), save(), load(). The v11 metagraph is a plain typed object with per-neuron records and no matrices:

mg = await client.subnets.metagraph(netuid=1)
for n in mg:                      # MetagraphNeuron, ordered by uid
    n.uid, n.hotkey, n.coldkey
    n.incentive, n.dividends, n.rank, n.trust, n.consensus   # 0..1 floats
    n.emission, n.alpha_stake, n.tao_stake, n.total_stake    # Balance
    n.axon                        # "ip:port" or None
mg.hotkeys, mg.coldkeys, mg.validators
mg.neuron(5), mg.by_hotkey("5F...")

Transactions

Every old transaction method maps to an intent class executed with client.execute(intent, wallet). Trailing kwargs move as follows: wait_for_inclusion / wait_for_finalization / period are kwargs of execute; raise_error=True becomes result.raise_for_failure(); mev_protection becomes mev_shield (on by default for stake-trading intents). The safe_staking / rate_tolerance / allow_partial_stake flags become the explicit *Limit intent variants with a limit_price_rao (see slippage for converting a tolerance to a limit price).

Dynamic dispatch (the old pattern of calling methods by name) becomes sub.intents.build(op, args_dict) or client.execute_tool(op, args_dict, wallet) — see For agents.

New in v11, worth adopting during migration: client.plan(intent, wallet) previews fee, effects, and warnings without submitting, and a sub.Policy(max_spend_tao=..., allowed_netuids=[...]) on the client hard-bounds what any execution may do.

Weights, children, and take

Three call families changed units, not just names:

• Weights are easier: pass floats (any scale — only proportions matter) or a {uid: weight} dict to sub.SetWeights; clipping, normalization, and u16 quantization happen internally (bittensor.intents.normalize is the canonical implementation). bittensor.utils.weight_utils (process_weights_for_netuid, convert_weights_and_uids_for_emit, ...) is gone and unnecessary. set_weights also auto-selects plain vs timelocked commit-reveal submission; drop any manual commit/reveal scheduling unless you used salt-based commits. version_key now defaults to 0 instead of the SDK version number — pass the subnet's required key explicitly if it enforces one.
• Take still accepts the float 0–1 form (take=0.18); a plain integer is the raw u16 proportion (take=11796), following the hyperparameter value rules (a decimal point marks the human form). set_delegate_take's auto-direction behavior is preserved by sub.SetTake; sub.IncreaseTake / sub.DecreaseTake pin the direction.
• Children proportions likewise accept floats 0–1 (children=[[0.5, "5F...child"]]); a plain integer is the raw u64 share of u64::MAX.

Money and Balance

Balance survives but is stricter — the biggest silent-behavior change in v11 (Money):

• Every Balance carries a netuid (0 = TAO). Arithmetic or comparison across units raises sub.UnitMismatchError (was BalanceUnitMismatchError); comparing with a bare float raises TypeError.
• .tao on an alpha balance raises instead of returning a number. Use .amount for the value in its own currency, or the stake-value-for-coldkey read to value alpha in TAO.
• Balance.from_tao(amount) no longer takes a netuid; Balance.from_alpha(amount, netuid=...) is the alpha constructor. Shorthands: sub.tao(1.5), sub.alpha(2.5, 42), sub.rao(1_500_000_000).
• Intent amount fields are unit-named (amount_tao, amount_alpha, limit_price_rao) and accept int | float | str | Decimal | Balance — the strict "must be a Balance object" rule from v10 is relaxed because the field name now carries the unit. Fields that support it accept "all".

Wallets

bittensor_wallet is replaced by bittensor.wallet with the same on-disk format — same paths (~/.bittensor/wallets/<name>/), same keyfile encryption (NaCl / legacy), same SS58 format. Existing wallets just work.

from bittensor.wallet import Wallet
wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")   # same constructor
wallet.coldkey, wallet.hotkey, wallet.coldkeypub          # same properties
wallet.create_new_coldkey(...), wallet.regenerate_coldkey(...)

Differences: bt.Wallet(config=...) and Wallet.add_args are gone (pass name/hotkey/path directly); bt.Keypair / bt.Keyfile are no longer top-level exports (bittensor.keyfiles.Keyfile exists; keypairs come from the wallet). Convenience helpers live in sub.wallets (create, regen_coldkey, list_wallets, sign_message, verify_message, ...). Non-interactive unlock: BT_WALLET_PASSWORD or BT_WALLET_PASSWORD_FILE (wallets).

Axon, Dendrite, and Synapse are gone

v11 contains no miner/validator networking stack: bt.Axon, bt.Dendrite, bt.Synapse, bt.StreamingSynapse, bt.SubnetsAPI, and bt.Tensor do not exist. What the old stack actually provided splits into three layers, and each has a v11 answer:

The chain-side operations remain — publish your endpoint with sub.ServeAxon (see Mining), set weights with sub.SetWeights (see Validating). The identity layer — hotkey-signed HTTP requests, replacing the old bt_header_* scheme with a cleaner cross-language wire format (btauth/1) — ships in the SDK as pure sign/verify functions with no server or client attached. A miner that must keep accepting old-SDK validators during a transition can also verify the legacy v10 header format (recipe in the guide).

Results and errors

result = await client.execute(intent, wallet)
if not result.success:
    match result.error.code:
        case sub.ErrorCode.RATE_LIMITED: ...        # wait and retry
        case sub.ErrorCode.INSUFFICIENT_BALANCE: ...
        case _: log(result.error.remediation)

CLI migration

One binary, still called btcli, now installed with bittensor. The structure: every read is btcli query <name>, every transaction is btcli tx <name> (intent op names with dashes), and familiar groups (wallet, stake, subnets, sudo, weights, axon, proxy, ...) wrap the same machinery. The v9 group shorthands (w, st, s, su, c, wt, cr, d) and snake_case command spellings (wallet new_hotkey) still work as hidden aliases. Full details: The CLI.

Global flags

Config file moves from ~/.bittensor/config.yml to ~/.bittensor/btcli.json and keys are renamed: btcli config set network finney, btcli config set wallet my_coldkey (was wallet_name). The old use_cache, rate_tolerance, safe_staking, allow_partial_stake, and dashboard_path keys have no equivalent. Non-interactive behavior changed for the better: without a TTY and without --yes, a mutation is declined with exit code 1 instead of hanging; missing required options exit 2.

Command mapping

Two new commands help automated migration directly: btcli tools dumps the full transaction catalog with JSON schemas, and btcli explain <code> explains any error code.

Migration checklist

1. Replace bittensor + bittensor-cli + bittensor_wallet with a single pinned bittensor>=11 (the CLI is included). In live environments, uninstall the old packages before upgrading (why).
2. Swap bt.Subtensor / bt.AsyncSubtensor for sub.SyncClient / sub.Client; move block=-pinned reads onto client.at(block).
3. Rewrite reads using the tables above; anything unmapped goes through client.query(sub.storage...).
4. Rewrite each transaction as an intent + client.execute; take values and child proportions keep working as 0–1 floats (plain integers mean the raw u16/u64 wire values); replace safe-staking flags with *Limit intents.
5. Update result handling: .success still works, but branch on result.error.code instead of exception types or message strings.
6. Fix Balance usage: no .tao on alpha, no cross-unit arithmetic, from_alpha for subnet currency.
7. Delete bt.config/argparse plumbing, bt.logging calls (use standard logging), and weight_utils preprocessing.
8. Update env vars (BT_SUBTENSOR_NETWORK → BT_NETWORK, BT_WALLET_NAME → BT_WALLET) and shell scripts per the CLI tables (--wallet.name → -w, --json-output → --json, --no-prompt → --yes).
9. If the script served an axon or queried miners with a dendrite, rebuild that layer on your own HTTP stack with sub.http_auth for the hotkey signing (Signed requests); only its chain calls move to this SDK's client.
10. Dry-run everything: client.plan(...) in Python, --dry-run on the CLI, ideally against test or a local node first.