TensorFlow · Class

tf.Variable

tf.Variable represents mutable TensorFlow state backed by a tensor. Its initial value establishes the variable's dtype and shape, and assign methods update its value.

How it works

tf.Variable stores mutable TensorFlow state. Its initial value establishes the variable's dtype and shape; later updates use assignment methods, while TensorFlow can track trainable variables for optimization and capture variables inside tf.function.

Syntax

tf.Variable(
    initial_value=None,
    trainable=None,
    validate_shape=True,
    caching_device=None,
    name=None,
    variable_def=None,
    dtype=None,
    import_scope=None,
    constraint=None,
    synchronization=tf.VariableSynchronization.AUTO,
    aggregation=tf.compat.v1.VariableAggregation.NONE,
    shape=None,
    experimental_enable_variable_lifting=True
)

Parameters

Name	Type	Description
`initial_value`	`Tensor or Python object convertible to Tensor`	Initial Tensor or Python-convertible value; a zero-argument callable is also accepted.
`trainable`	`bool or None`	Whether the variable is trainable; defaults to True.
`validate_shape`	`bool`	Whether to validate the initial shape; defaults to True.
`name`	`str or None`	Optional variable name, automatically uniquified when omitted.
`dtype`	`tf.dtypes.DType or None`	Optional dtype to which the initial value is converted.
`shape`	`tf.TensorShape or None`	Optional variable shape; when omitted, the initial value's shape is used.
`synchronization`	`tf.VariableSynchronization`	Synchronization policy for distributed variables.
`aggregation`	`tf.compat.v1.VariableAggregation`	Aggregation policy for distributed updates.

Returns

A tf.Variable instance representing mutable TensorFlow state.

Key points

Use tf.Variable when a program needs state that persists and can be shared across operations.
Construction requires an initial value, and that value may have any TensorFlow-supported type and shape.
The constructor derives the variable's dtype and shape from its initial value unless corresponding options override them.
A variable normally retains its dtype and shape after creation.
Update state with methods such as assign, assign_add, or assign_sub rather than replacing the variable object.
tf.function can capture variables so traced computations can read and update their state.

Common mistakes

If the initial value has no known shape, construction requires an explicit shape unless validation is disabled.
An unspecified shape permits assignments with differing shapes, unlike the normal fixed-shape behavior.
Callable initializers need an explicitly supplied dtype.

Example: Mutable counter

import tensorflow as tf

step = tf.Variable(0, dtype=tf.int32, trainable=False)
step.assign_add(1)
print(step.numpy())

Creates non-trainable integer state, updates it in place, and reads its current value.

When to use it

Store weights and other values updated by an optimizer.

Model parameters

Maintain mutable counters or other application state across operations.

Persistent counters

Capture and update state from functions decorated with tf.function.

Compiled computation

Interview questions

QWhat is tf.Variable, and how is it different from a tensor?

A tf.Variable is mutable TensorFlow state backed by a tensor. Its constructor's initial value determines its dtype and shape, and assign-style methods change the stored value.

Follow-up: How can a variable participate in optimization? Mark it trainable, allowing higher-level training code to treat it as a trainable model parameter.

QWhat forms can initial_value take?

The initial_value argument accepts a Tensor or a Python object convertible to a Tensor. It may also be a zero-argument callable; in that case, dtype must be provided.

Follow-up: What happens if validation is disabled? An initial value may omit a specified shape, but assignments still need to satisfy the variable's configured shape rules.

QWhat does trainable mean for a variable?

trainable controls whether the variable is considered trainable, and the documented default is True. Variables are also commonly captured and manipulated by tf.function.

Follow-up: Why set trainable=False? Use it for persistent state such as counters or bookkeeping that should not be optimized as a model parameter.

tf.Variable.assign
tf.Variable.assign_add
tf.Variable.assign_sub
tf.Tensor
tf.function
tf.Module

Source: tf.Variable. Checked 2026-10-15.