Introduction

In TensorFlow, a variable being trainable means it is intended to be updated by the learning process. In practical terms, trainable variables are the ones optimizers look at when applying gradients during model training.

What trainable=True Actually Changes

When a tf.Variable is marked trainable, TensorFlow and Keras include it in collections such as model.trainable_variables. That is the list usually used during backpropagation and optimizer updates.

1import tensorflow as tf
2
3w = tf.Variable([1.0, 2.0], trainable=True)
4b = tf.Variable([0.5], trainable=False)
5
6print(w.trainable)  # True
7print(b.trainable)  # False

Both variables are mutable, but only the trainable one is automatically treated as a learnable parameter.

Trainable Does Not Mean Mutable Versus Immutable

This is a common misunderstanding. A non-trainable variable can still be changed programmatically with assignment operations. The trainable flag does not lock the value. It tells the training system whether the variable should participate in gradient-based optimization by default.

That is why trainable=False means "not updated by the optimizer automatically," not "cannot change at all."

How This Shows Up in Keras Layers

In Keras models, trainable weights usually correspond to layer parameters such as kernels and biases.

1layer = tf.keras.layers.Dense(8)
2layer.build((None, 4))
3
4print(layer.trainable_variables)
5print(layer.non_trainable_variables)

If you freeze a layer:

layer.trainable = False

its weights move out of the trainable set, which is why transfer learning often freezes base layers while leaving the new classification head trainable.

Why Non-Trainable Variables Exist

Some values in a model are state, but not learnable parameters. Examples include:

• moving statistics in batch normalization,
• counters or step trackers,
• cached values or manually controlled state.

Those values may change over time, but not by ordinary gradient descent.

A Good Mental Model

A useful rule is:

• trainable variable: optimizer should learn this value,
• non-trainable variable: model may store or update this value, but it is not part of the learnable parameter set by default.

That distinction becomes important when freezing layers, debugging gradients, or inspecting why certain weights are not changing during training.

Debugging Usually Starts with the Variable Lists

When weights are not changing during training, one of the first checks should be model.trainable_variables versus model.non_trainable_variables. That quickly reveals whether a layer was frozen intentionally, frozen accidentally, or excluded from optimization for architectural reasons.

Manual Gradient Code Can Override the Usual Pattern

In custom training loops, you can still choose which variables to pass to tape.gradient(...) and optimizer.apply_gradients(...). That means trainable is the default training contract, but advanced code can still take manual control when needed.

Transfer Learning Makes This Especially Visible

When people freeze a pretrained backbone and train only a new head, they are working directly with the trainable-versus-non-trainable distinction. It is one of the most concrete real-world examples of why the flag exists at all.

Common Pitfalls

• Assuming non-trainable variables are immutable.
• Forgetting that frozen Keras layers remove their weights from the trainable set.
• Debugging optimizer behavior without checking model.trainable_variables.
• Expecting every variable in a model to receive gradients automatically.
• Confusing runtime state variables with learnable parameters.

Summary

• A trainable TensorFlow variable is one intended to be updated by the training process.
• Trainable variables are typically included in optimizer-managed weight updates.
• Non-trainable variables can still change, but not through ordinary optimizer behavior by default.
• Keras layer freezing works by changing which variables count as trainable.
• The key distinction is optimizer participation, not basic mutability.