# How to Configure Vnodes (num_tokens) for Optimal Cassandra Cluster Balance

> Optimize Cassandra cluster balance by configuring vnodes (num_tokens). Learn how to set num_tokens for homogeneous and heterogeneous clusters to ensure efficient token distribution.

- Repository: [The Apache Software Foundation/cassandra](https://github.com/apache/cassandra)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Set `num_tokens` to 16 in [`conf/cassandra.yaml`](https://github.com/apache/cassandra/blob/main/conf/cassandra.yaml) for homogeneous clusters, or assign proportionally higher values (32–64) to more powerful nodes in heterogeneous environments to weight token ownership by hardware capacity.**

Apache Cassandra distributes data across the cluster using *virtual nodes* (vnodes) defined by the `num_tokens` parameter. Properly configuring this setting in [`conf/cassandra.yaml`](https://github.com/apache/cassandra/blob/main/conf/cassandra.yaml) ensures uniform data distribution and prevents hot spots that degrade performance. When calibrated correctly, vnodes minimize the operational impact of node failures and accelerate the bootstrapping of new nodes into the ring.

## Understanding Vnodes and Token Distribution

Vnodes divide the continuous hash ring into discrete ranges, allowing each physical node to own multiple non-contiguous token ranges. The **Murmur3Partitioner** hashes each row’s primary key into a 64-bit token, and the allocation algorithm places virtual tokens uniformly around the ring to balance the replicated load across the cluster.

### The Role of num_tokens in Load Balancing

The `num_tokens` setting determines how many token ranges each node manages. A higher count provides finer granularity, allowing the cluster to distribute data more precisely according to node capacity. Conversely, nodes with fewer tokens own larger contiguous ranges of the token space, which concentrates data and request traffic, creating performance bottlenecks.

## Recommended num_tokens Values by Cluster Profile

Choosing the correct value depends on cluster size and hardware uniformity. According to the Apache Cassandra source code, the default configuration ships with `num_tokens: 16`, which serves as a pragmatic baseline that balances distribution quality against metadata overhead.

### Small Clusters (3 Nodes or Fewer)

For clusters with three or fewer nodes, maintain the default value of **16** or increase modestly to **32**. This provides sufficient granularity for balanced distribution without unnecessarily inflating the size of system tables that track token assignments.

### Medium-to-Large Clusters (4+ Nodes)

In larger deployments, the default **16** tokens per node typically delivers optimal balance. You may increase this to **32** or **64** to further reduce the impact of a single node failure, as the workload redistributes across more, smaller token ranges. However, each additional token increases overhead for gossip communication and repair operations, so load test before deploying higher values in production.

### Heterogeneous Hardware Environments

When nodes have different CPU, memory, or storage capacities, assign **num_tokens** proportionally to hardware strength. Configure powerful nodes with **32** or **64** tokens and weaker nodes with **16** (or lower). This weights token ownership by capacity, ensuring that high-performance nodes handle proportionally more data and traffic than resource-constrained peers.

## How Cassandra Assigns Tokens at Startup

When a node starts, Cassandra checks the `num_tokens` setting in [`conf/cassandra.yaml`](https://github.com/apache/cassandra/blob/main/conf/cassandra.yaml) located at lines 42–50. If the node has no `initial_token` defined, the **auto-allocation algorithm** implemented in [`src/java/org/apache/cassandra/allocator/TokenAllocation.java`](https://github.com/apache/cassandra/blob/main/src/java/org/apache/cassandra/allocator/TokenAllocation.java) automatically computes token positions that minimize overlap with existing nodes while respecting the replication factor of each keyspace. This automatic allocation is only supported when using the `Murmur3Partitioner`.

If `initial_token` is explicitly defined, that list overrides automatic allocation, and Cassandra assigns the exact tokens specified rather than calculating an optimal distribution.

## Configuring num_tokens in Production

Edit the primary configuration file to adjust virtual node counts. The following example increases the token count to 32 for a node in a large cluster:

```yaml

# conf/cassandra.yaml

# Lines 42-50 contain the num_tokens definition

num_tokens: 32

```

To bootstrap a new node with a custom token count (for example, 64 tokens on a high-capacity server):

```bash

# Set the token count on the new host before starting Cassandra

sed -i 's/^num_tokens:.*/num_tokens: 64/' /etc/cassandra/conf/cassandra.yaml

# Start the service; TokenAllocation.java will compute 64 optimal positions

systemctl start cassandra

```

## Verifying Token Distribution

After startup or topology changes, verify that tokens distribute evenly across the cluster:

```bash

# Display node status and ownership percentages

nodetool status

# View detailed token ranges per node (requires authentication if enabled)

nodetool ring -u username -pw password

```

The `owns` column in `nodetool status` should show approximately equal percentages across all nodes with identical `num_tokens` values. Significant deviations indicate configuration errors or uneven token assignment.

## Summary

- **Default choice**: Use `num_tokens: 16` in [`conf/cassandra.yaml`](https://github.com/apache/cassandra/blob/main/conf/cassandra.yaml) for most production clusters with homogeneous hardware.
- **Scale considerations**: Increase to 32 or 64 in large clusters to improve failure isolation, but monitor gossip and repair overhead.
- **Hardware weighting**: Assign higher values to powerful nodes and lower values to weak nodes to balance load proportionally.
- **Automatic allocation**: Rely on the algorithm in [`TokenAllocation.java`](https://github.com/apache/cassandra/blob/main/TokenAllocation.java) by leaving `initial_token` unset; manual token assignment bypasses automatic balancing.
- **Verification**: Always confirm distribution with `nodetool status` and `nodetool ring` after configuration changes.

## Frequently Asked Questions

### What is the default num_tokens value in Cassandra?

The default value is **16**. This is defined in [`conf/cassandra.yaml`](https://github.com/apache/cassandra/blob/main/conf/cassandra.yaml) and provides a practical balance between fine-grained data distribution and manageable system table overhead for most deployments.

### Can I change num_tokens on an existing node?

No. Changing `num_tokens` on a node that has already joined the cluster requires decommissioning the node, wiping the data directory, and re-bootstrapping it with the new value. Modifying this setting live can cause token collisions and data inconsistency.

### How does num_tokens affect repair operations?

Each additional token increases the metadata managed by the gossip protocol and creates more discrete token ranges that require individual repair operations. While values of 32 or 64 improve balance, they generate more repair tasks than the default 16, potentially increasing system load during maintenance windows.

### Does Cassandra support automatic token allocation with all partitioners?

No. The automatic token allocation algorithm implemented in [`TokenAllocation.java`](https://github.com/apache/cassandra/blob/main/TokenAllocation.java) only functions with the `Murmur3Partitioner`. If you use the `RandomPartitioner` or a custom partitioner, you must manually specify token assignments using the `initial_token` configuration parameter.