Introduction

In TensorFlow, assigning values by index depends on whether you are working with an immutable tensor or a mutable tf.Variable. Plain tensors are not updated in place. Instead, you build a new tensor with the desired changes. Variables, on the other hand, support mutation through scatter-style update methods.

So the first question is not “what are the indices?” It is “am I updating a tensor value functionally, or am I mutating a variable?” Once that is clear, the correct API is usually straightforward.

Updating an Immutable Tensor

For plain tensors, use tf.tensor_scatter_nd_update.

1import tensorflow as tf
2
3x = tf.constant([
4    [1, 2, 3],
5    [4, 5, 6],
6], dtype=tf.int32)
7
8y = tf.tensor_scatter_nd_update(
9    x,
10    indices=[[0, 1], [1, 2]],
11    updates=[20, 99],
12)
13
14print(x.numpy())
15print(y.numpy())

x stays unchanged. y is the updated tensor.

This is the modern TensorFlow 2 answer when you want functional tensor transformation.

Updating a Mutable Variable

If you actually have a tf.Variable, use its scatter update methods.

1import tensorflow as tf
2
3v = tf.Variable([
4    [1, 2, 3],
5    [4, 5, 6],
6], dtype=tf.int32)
7
8v.scatter_nd_update(
9    indices=[[0, 1], [1, 2]],
10    updates=[20, 99],
11)
12
13print(v.numpy())

This mutates the variable in place.

That is usually what you want when state must persist across later steps in the same program.

Understanding the Index Format

Indices are provided as coordinate lists. For a 2D tensor:

• '[row, col] selects one element'
• '[row] selects one entire row'

That means the shape of updates must match what each index selects.

For example, whole-row replacement looks like this:

1v = tf.Variable([
2    [1, 2, 3],
3    [4, 5, 6],
4], dtype=tf.int32)
5
6v.scatter_nd_update(
7    indices=[[1]],
8    updates=[[40, 50, 60]],
9)
10
11print(v.numpy())

Here each index selects a row, so each update must also be a row.

When You Have Many Sparse Updates

Scatter-based updates are particularly useful when:

• the tensor is large
• only a few positions change
• building a full replacement tensor would be wasteful

That is why indexed updates appear often in recommendation systems, sparse processing, and custom training logic.

Avoid Python-Style Assignment Assumptions

TensorFlow is not a Python list. You cannot treat a tensor like a mutable nested list and expect in-place assignment syntax everywhere.

This does not work for plain tensors the way Python developers might expect:

• assign by bracket notation
• mutate elements directly inside a constant tensor
• rely on hidden side effects during graph-style computation

TensorFlow enforces the distinction between immutable tensors and mutable variables deliberately.

Common Pitfalls

A common mistake is trying to mutate a tf.Tensor directly when only tf.Variable supports stateful mutation.

Another mistake is giving indices whose depth does not match the slice shape you are trying to update.

Developers also confuse row-level updates with element-level updates. The index length decides what slice is targeted.

Finally, many older examples use TensorFlow 1 compatibility APIs. In modern TensorFlow 2 code, tf.tensor_scatter_nd_update and variable.scatter_nd_update(...) are usually the clearer tools.

It is also worth printing shapes during debugging, because most scatter errors are really shape errors in disguise.

Summary

• Use tf.tensor_scatter_nd_update for immutable tensor updates that return a new tensor.
• Use tf.Variable.scatter_nd_update(...) when you need in-place mutation of a variable.
• Index depth determines whether you update an element, a row, or a larger slice.
• The shape of updates must match the slice selected by each index.
• Most TensorFlow index-assignment problems become simple once you separate immutable tensors from mutable variables.