ML Community Day is November 9! Join us for updates from TensorFlow, JAX, and more Learn more


Represents a (possibly partial) specification for a TensorFlow device.

Inherits From: DeviceSpec

DeviceSpecs are used throughout TensorFlow to describe where state is stored and computations occur. Using DeviceSpec allows you to parse device spec strings to verify their validity, merge them or compose them programmatically.


# Place the operations on device "GPU:0" in the "ps" job.
device_spec = DeviceSpec(job="ps", device_type="GPU", device_index=0)
with tf.device(device_spec.to_string()):
  # Both my_var and squared_var will be placed on /job:ps/device:GPU:0.
  my_var = tf.Variable(..., name="my_variable")
  squared_var = tf.square(my_var)

With eager execution disabled (by default in TensorFlow 1.x and by calling disable_eager_execution() in TensorFlow 2.x), the following syntax can be used:


# Same as previous
device_spec = DeviceSpec(job="ps", device_type="GPU", device_index=0)
# No need of .to_string() method.
with tf.device(device_spec):
  my_var = tf.Variable(..., name="my_variable")
  squared_var = tf.square(my_var)

If a DeviceSpec is partially specified, it will be merged with other DeviceSpecs according to the scope in which it is defined. DeviceSpec components defined in inner scopes take precedence over those defined in outer scopes.

gpu0_spec = DeviceSpec(job="ps", device_type="GPU", device_index=0)
with tf.device(DeviceSpec(job="train").to_string()):
  with tf.device(gpu0_spec.to_string()):
    # Nodes created here will be assigned to /job:ps/device:GPU:0.
  with tf.device(DeviceSpec(device_type="GPU", device_index=1).to_string()):
    # Nodes created here will be assigned to /job:train/device:GPU:1.

A DeviceSpec consists of 5 components -- each of which is optionally specified:

  • Job: The job name.
  • Replica: The replica index.
  • Task: The task index.
  • Device type: The device type string (e.g. "CPU" or "GPU").
  • Device index: The device index.

job string. Optional job name.
replica int. Optional replica index.
task int. Optional task index.
device_type Optional device type string (e.g. "CPU" or "GPU")
device_index int. Optional device index. If left unspecified, device represents 'any' device_index.








View source

Construct a DeviceSpec from a string.

spec a string of the form /job:/replica:/task:/device:CPU: or /job:/replica:/task:/device:GPU: as cpu and gpu are mutually exclusive. All entries are optional.

A DeviceSpec.


View source

Returns a new DeviceSpec which incorporates dev.

When combining specs, dev will take precedence over the current spec. So for instance:

first_spec = tf.DeviceSpec(job=0, device_type="CPU")
second_spec = tf.DeviceSpec(device_type="GPU")
combined_spec = first_spec.make_merged_spec(second_spec)

is equivalent to: