TensorFlow has two fundamental data structures that every practitioner encounters early on: tf.Tensor and tf.Variable. At first glance they look similar because both hold multi-dimensional arrays of numbers. But they serve very different purposes. A Tensor is an immutable value produced by an operation, while a Variable is a mutable container designed to hold state that changes over time, like model weights. Understanding this distinction is essential for writing correct and efficient TensorFlow code.

What Is a Tensor?

A tf.Tensor is TensorFlow's core data structure. It represents a multi-dimensional array with a uniform data type. Tensors are the values that flow between operations in a computation graph.

The key property of a tensor is that it is immutable. Once created, its values cannot be changed. If you need different values, you create a new tensor.

1import tensorflow as tf
2
3# Creating tensors
4scalar = tf.constant(5)                     # 0-D tensor (scalar)
5vector = tf.constant([1, 2, 3])             # 1-D tensor (vector)
6matrix = tf.constant([[1, 2], [3, 4]])      # 2-D tensor (matrix)
7
8print(scalar.shape)  # ()
9print(vector.shape)  # (3,)
10print(matrix.shape)  # (2, 2)
11
12# Tensors are immutable: operations produce new tensors
13result = matrix * 2  # New tensor, original unchanged
14print(result)        # tf.Tensor([[2 4] [6 8]], shape=(2, 2), dtype=int32)

Tensors are typically used for input data, intermediate computation results, and model outputs. They are stateless, meaning they do not persist values across different calls to a function.

What Is a Variable?

A tf.Variable is a mutable container that wraps a tensor. It is specifically designed to hold values that need to change during training, such as weights and biases.

1# Creating a variable
2weights = tf.Variable(tf.random.normal([3, 2]), name="weights")
3bias = tf.Variable(tf.zeros([2]), name="bias")
4
5print(weights.shape)  # (3, 2)
6print(bias.numpy())   # [0. 0.]

Unlike tensors, variables can be updated in place using methods like .assign(), .assign_add(), and .assign_sub().

1# Modifying a variable in place
2bias.assign([0.1, 0.2])
3print(bias.numpy())  # [0.1 0.2]
4
5bias.assign_add([0.01, 0.01])
6print(bias.numpy())  # [0.11 0.21]

This mutability is what makes variables suitable for model parameters. During training, the optimizer computes gradients and then calls .assign_sub() to update each variable by subtracting the gradient scaled by the learning rate.

Key Differences at a Glance

Mutability. Tensors are immutable. Variables are mutable and support in-place updates.

Purpose. Tensors represent data values and computation results. Variables represent persistent, trainable state.

Gradient tracking. Variables are tracked by tf.GradientTape by default, which means TensorFlow automatically computes gradients with respect to them. Regular tensors are not tracked unless you explicitly call tape.watch().

1x = tf.Variable(3.0)
2
3with tf.GradientTape() as tape:
4    y = x ** 2
5
6grad = tape.gradient(y, x)
7print(grad.numpy())  # 6.0 (derivative of x^2 is 2x, evaluated at x=3)

Lifecycle. A tensor is typically a temporary value that exists only as long as it is referenced. A variable persists across function calls and training steps, maintaining its value until explicitly changed.

Storage. Variables have additional infrastructure for checkpointing and saving. When you call model.save() or use tf.train.Checkpoint, it is the variables that get serialized to disk.

How Variables and Tensors Work Together

In practice, variables and tensors collaborate constantly. A forward pass through a neural network multiplies input tensors by weight variables, adds bias variables, and produces output tensors. The optimizer then updates the variables based on the loss.

1# Simple linear model
2W = tf.Variable(tf.random.normal([784, 10]))
3b = tf.Variable(tf.zeros([10]))
4
5def predict(x):
6    return tf.matmul(x, W) + b  # x is a tensor, W and b are variables
7
8# Training step
9def train_step(x, y_true, learning_rate=0.01):
10    with tf.GradientTape() as tape:
11        y_pred = predict(x)
12        loss = tf.reduce_mean(tf.square(y_pred - y_true))
13
14    gradients = tape.gradient(loss, [W, b])
15    W.assign_sub(learning_rate * gradients[0])
16    b.assign_sub(learning_rate * gradients[1])
17
18    return loss

Here, x and y_true are tensors (input data), W and b are variables (trainable parameters), and loss and y_pred are tensors (computation results). The gradient tape watches the variables automatically and the .assign_sub() calls modify them in place.

Common Pitfalls

Treating variables like tensors in arithmetic. Variables support the same math operations as tensors, but if you accidentally create a new tensor instead of updating the variable, you lose the in-place update. Use .assign() instead of = for updates.

1# Wrong: creates a new tensor, does not update the variable
2W = W - learning_rate * gradient  # W is now a tensor, not a variable
3
4# Correct: updates the variable in place
5W.assign_sub(learning_rate * gradient)

Forgetting to initialize variables. In TF2 eager mode, variables are initialized at creation. But in TF1-style graph mode, variables must be explicitly initialized with tf.global_variables_initializer(). This distinction trips up developers migrating between TF versions.

Not understanding gradient tape tracking. By default, GradientTape only watches tf.Variable objects. If you need gradients with respect to a tensor, you must call tape.watch(tensor) explicitly. Forgetting this results in None gradients.

Creating variables inside a training loop. If you instantiate a tf.Variable inside your training loop, a new variable is created on every iteration, which wastes memory and breaks gradient tracking. Always create variables outside the loop.

Summary

A tf.Tensor is an immutable multi-dimensional array that represents data and computation results. A tf.Variable is a mutable wrapper around a tensor designed to hold state that persists and changes over time, such as model weights. Tensors are stateless and temporary. Variables are stateful and persistent. During training, input data flows through the model as tensors, gradients are computed with respect to variables, and the optimizer updates those variables in place. Understanding this division of labor is fundamental to working effectively with TensorFlow.