# tf.TensorShape

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L743-L1438) |

Represents the shape of a `Tensor`.

Inherits From: [`TraceType`](https://www.tensorflow.org/versions/r2.10/api_docs/python/tf/types/experimental/TraceType)

#### View aliases


**Compat aliases for migration**

See
[Migration guide](https://www.tensorflow.org/guide/migrate) for
more details.

[`tf.compat.v1.TensorShape`](https://www.tensorflow.org/api_docs/python/tf/TensorShape)

<br />

    tf.TensorShape(
        dims
    )

A `TensorShape` represents a possibly-partial shape specification for a
`Tensor`. It may be one of the following:

- *Fully-known shape:* has a known number of dimensions and a known size for each dimension. e.g. `TensorShape([16, 256])`
- *Partially-known shape:* has a known number of dimensions, and an unknown size for one or more dimension. e.g. `TensorShape([None, 256])`
- *Unknown shape:* has an unknown number of dimensions, and an unknown size in all dimensions. e.g. `TensorShape(None)`

If a tensor is produced by an operation of type `"Foo"`, its shape
may be inferred if there is a registered shape function for
`"Foo"`. See [Shape
functions](https://www.tensorflow.org/guide/create_op#shape_functions_in_c)
for details of shape functions and how to register them. Alternatively,
you may set the shape explicitly using [`tf.Tensor.set_shape`](https://www.tensorflow.org/versions/r2.10/api_docs/python/tf/Tensor#set_shape).

<br />

<br />

<br />

| ## Args ||
|---|---|
| `dims` | A list of Dimensions, or None if the shape is unspecified. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If dims cannot be converted to a list of dimensions. |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `dims` | Deprecated. Returns list of dimensions for this shape. <br /> Suggest [`TensorShape.as_list`](https://www.tensorflow.org/versions/r2.10/api_docs/python/tf/TensorShape#as_list) instead. |
| `ndims` | Deprecated accessor for `rank`. |
| `rank` | Returns the rank of this shape, or None if it is unspecified. |

<br />

## Methods

### `as_list`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1353-L1364)

    as_list()

Returns a list of integers or `None` for each dimension.

<br />

<br />

<br />

| Returns ||
|---|---|
| A list of integers or `None` for each dimension. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` is an unknown shape with an unknown rank. |

<br />

### `as_proto`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1366-L1374)

    as_proto()

Returns this shape as a `TensorShapeProto`.

### `assert_has_rank`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1045-L1055)

    assert_has_rank(
        rank
    )

Raises an exception if `self` is not compatible with the given `rank`.

<br />

<br />

<br />

| Args ||
|---|---|
| `rank` | An integer. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` does not represent a shape with the given `rank`. |

<br />

### `assert_is_compatible_with`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1294-L1307)

    assert_is_compatible_with(
        other
    )

Raises exception if `self` and `other` do not represent the same shape.

This method can be used to assert that there exists a shape that both
`self` and `other` represent.

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another TensorShape. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` and `other` do not represent the same shape. |

<br />

### `assert_is_fully_defined`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1344-L1351)

    assert_is_fully_defined()

Raises an exception if `self` is not fully defined in every dimension.

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` does not have a known value for every dimension. |

<br />

### `assert_same_rank`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1029-L1043)

    assert_same_rank(
        other
    )

Raises an exception if `self` and `other` do not have compatible ranks.

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another `TensorShape`. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` and `other` do not represent shapes with the same rank. |

<br />

### `concatenate`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1006-L1027)

    concatenate(
        other
    )

Returns the concatenation of the dimension in `self` and `other`.

> [!NOTE]
> **Note:** If either `self` or `other` is completely unknown, concatenation will discard information about the other shape. In future, we might support concatenation that preserves this information for use with slicing.

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another `TensorShape`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `TensorShape` whose dimensions are the concatenation of the dimensions in `self` and `other`. ||

<br />

### `experimental_as_proto`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1242-L1244)

    experimental_as_proto() -> tensor_shape_pb2.TensorShapeProto

Returns a proto representation of the TensorShape instance.

### `experimental_from_proto`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1236-L1240)

    @classmethod
    experimental_from_proto(
        proto: tensor_shape_pb2.TensorShapeProto
    ) -> 'TensorShape'

Returns a TensorShape instance based on the serialized proto.

### `experimental_type_proto`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1231-L1234)

    @classmethod
    experimental_type_proto() -> Type[tensor_shape_pb2.TensorShapeProto]

Returns the type of proto associated with TensorShape serialization.

### `is_compatible_with`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1247-L1292)

    is_compatible_with(
        other
    )

Returns True iff `self` is compatible with `other`.

Two possibly-partially-defined shapes are compatible if there
exists a fully-defined shape that both shapes can represent. Thus,
compatibility allows the shape inference code to reason about
partially-defined shapes. For example:

- TensorShape(None) is compatible with all shapes.

- TensorShape(\[None, None\]) is compatible with all two-dimensional
  shapes, such as TensorShape(\[32, 784\]), and also TensorShape(None). It is
  not compatible with, for example, TensorShape(\[None\]) or
  TensorShape(\[None, None, None\]).

- TensorShape(\[32, None\]) is compatible with all two-dimensional shapes
  with size 32 in the 0th dimension, and also TensorShape(\[None, None\])
  and TensorShape(None). It is not compatible with, for example,
  TensorShape(\[32\]), TensorShape(\[32, None, 1\]) or TensorShape(\[64, None\]).

- TensorShape(\[32, 784\]) is compatible with itself, and also
  TensorShape(\[32, None\]), TensorShape(\[None, 784\]), TensorShape(\[None,
  None\]) and TensorShape(None). It is not compatible with, for example,
  TensorShape(\[32, 1, 784\]) or TensorShape(\[None\]).

The compatibility relation is reflexive and symmetric, but not
transitive. For example, TensorShape(\[32, 784\]) is compatible with
TensorShape(None), and TensorShape(None) is compatible with
TensorShape(\[4, 4\]), but TensorShape(\[32, 784\]) is not compatible with
TensorShape(\[4, 4\]).

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another TensorShape. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| True iff `self` is compatible with `other`. ||

<br />

### `is_fully_defined`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1339-L1342)

    is_fully_defined()

Returns True iff `self` is fully defined in every dimension.

### `is_subtype_of`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1115-L1173)

    is_subtype_of(
        other: https://www.tensorflow.org/versions/r2.10/api_docs/python/tf/types/experimental/TraceType
    ) -> bool

Returns True iff `self` is subtype of `other`.

Shape A is a subtype of shape B if shape B can successfully represent it:

- A `TensorShape` of any rank is a subtype of `TensorShape(None)`.

- TensorShapes of equal ranks are covariant, i.e.
  `TensorShape([A1, A2, ..])` is a subtype of
  `TensorShape([B1, B2, ..])` iff An is a subtype of Bn.

  An is subtype of Bn iff An == Bn or Bn is None.
- TensorShapes of different defined ranks have no subtyping relation.

The subtyping relation is reflexive and transitive, but not symmetric.

#### Some examples:

- `TensorShape([32, 784])` is a subtype of `TensorShape(None)`, and
  `TensorShape([4, 4])` is also a subtype of `TensorShape(None)` but
  `TensorShape([32, 784])` and `TensorShape([4, 4])` are not subtypes of
  each other.

- All two-dimensional shapes are subtypes of `TensorShape([None, None])`,
  such as `TensorShape([32, 784])`. There is no subtype relationship with,
  for example, `TensorShape([None])` or `TensorShape([None, None, None])`.

- `TensorShape([32, None])` is also a subtype of `TensorShape([None, None])`
  and `TensorShape(None)`. It is not a subtype of, for example,
  `TensorShape([32])`, `TensorShape([32, None, 1])`,
  `TensorShape([64, None])` or `TensorShape([None, 32])`.

- `TensorShape([32, 784])` is a subtype of itself, and also
  `TensorShape([32, None])`, `TensorShape([None, 784])`,
  `TensorShape([None, None])` and `TensorShape(None)`.
  It has no subtype relation with, for example, `TensorShape([32, 1, 784])`
  or `TensorShape([None])`.

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another `TensorShape`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| True iff `self` is subtype of `other`. ||

<br />

### `merge_with`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L946-L996)

    merge_with(
        other
    )

Returns a `TensorShape` combining the information in `self` and `other`.

The dimensions in `self` and `other` are merged element-wise,
according to the rules below:

    Dimension(n).merge_with(Dimension(None)) == Dimension(n)
    Dimension(None).merge_with(Dimension(n)) == Dimension(n)
    Dimension(None).merge_with(Dimension(None)) == Dimension(None)
    # raises ValueError for n != m
    Dimension(n).merge_with(Dimension(m))

> > ts = tf.TensorShape(\[1,2\])
> > ot1 = tf.TensorShape(\[1,2\])
> > ts.merge_with(ot).as_list()
> > \[1,2\]
> > ot2 = tf.TensorShape(\[1,None\])
> > ts.merge_with(ot2).as_list()
> > \[1,2\]
> > ot3 = tf.TensorShape(\[None, None\])
> > ot3.merge_with(ot2).as_list()
> > \[1, None\]

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another `TensorShape`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `TensorShape` containing the combined information of `self` and `other`. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` and `other` are not compatible. |

<br />

### `most_specific_common_supertype`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1175-L1229)

    most_specific_common_supertype(
        others: Sequence[https://www.tensorflow.org/versions/r2.10/api_docs/python/tf/types/experimental/TraceType]
    ) -> Optional['TensorShape']

Returns the most specific supertype `TensorShape` of self and others.

- `TensorShape([None, 1])` is the most specific `TensorShape` supertyping
  both `TensorShape([2, 1])` and `TensorShape([5, 1])`. Note that
  `TensorShape(None)` is also a supertype but it is not "most specific".

- `TensorShape([1, 2, 3])` is the most specific `TensorShape` supertyping
  both `TensorShape([1, 2, 3])` and `TensorShape([1, 2, 3]`). There are
  other less specific TensorShapes that supertype above mentioned
  TensorShapes, e.g. `TensorShape([1, 2, None])`, `TensorShape(None)`.

  - `TensorShape([None, None])` is the most specific `TensorShape`
    supertyping both `TensorShape([2, None])` and `TensorShape([None, 3])`.
    As always, `TensorShape(None)` is also a supertype but not the most
    specific one.

  - `TensorShape(None`) is the only `TensorShape` supertyping both
    `TensorShape([1, 2, 3])` and `TensorShape([1, 2])`. In general, any two
    shapes that have different ranks will only have `TensorShape(None)`
    as a common supertype.

  - `TensorShape(None)` is the only `TensorShape` supertyping both
    `TensorShape([1, 2, 3])` and `TensorShape(None)`. In general, the common
    supertype of any shape with `TensorShape(None)` is `TensorShape(None)`.

<br />

<br />

<br />

| Args ||
|---|---|
| `others` | Sequence of `TensorShape`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `TensorShape` which is the most specific supertype shape of `self` and `others`. None if it does not exist. ||

<br />

### `most_specific_compatible_shape`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1309-L1337)

    most_specific_compatible_shape(
        other
    )

Returns the most specific TensorShape compatible with `self` and `other`.

- TensorShape(\[None, 1\]) is the most specific TensorShape compatible with
  both TensorShape(\[2, 1\]) and TensorShape(\[5, 1\]). Note that
  TensorShape(None) is also compatible with above mentioned TensorShapes.

- TensorShape(\[1, 2, 3\]) is the most specific TensorShape compatible with
  both TensorShape(\[1, 2, 3\]) and TensorShape(\[1, 2, 3\]). There are more
  less specific TensorShapes compatible with above mentioned TensorShapes,
  e.g. TensorShape(\[1, 2, None\]), TensorShape(None).

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | Another `TensorShape`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `TensorShape` which is the most specific compatible shape of `self` and `other`. ||

<br />

### `num_elements`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L939-L944)

    num_elements()

Returns the total number of elements, or none for incomplete shapes.

### `with_rank`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1057-L1075)

    with_rank(
        rank
    )

Returns a shape based on `self` with the given rank.

This method promotes a completely unknown shape to one with a
known rank.

<br />

<br />

<br />

| Args ||
|---|---|
| `rank` | An integer. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A shape that is at least as specific as `self` with the given rank. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` does not represent a shape with the given `rank`. |

<br />

### `with_rank_at_least`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1077-L1094)

    with_rank_at_least(
        rank
    )

Returns a shape based on `self` with at least the given rank.

<br />

<br />

<br />

| Args ||
|---|---|
| `rank` | An integer. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A shape that is at least as specific as `self` with at least the given rank. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` does not represent a shape with at least the given `rank`. |

<br />

### `with_rank_at_most`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1096-L1113)

    with_rank_at_most(
        rank
    )

Returns a shape based on `self` with at most the given rank.

<br />

<br />

<br />

| Args ||
|---|---|
| `rank` | An integer. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A shape that is at least as specific as `self` with at most the given rank. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `self` does not represent a shape with at most the given `rank`. |

<br />

### `__add__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L998-L999)

    __add__(
        other
    )

### `__bool__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L872-L874)

    __bool__()

Returns True if this shape contains non-zero information.

### `__concat__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1437-L1438)

    __concat__(
        other
    )

### `__eq__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1376-L1429)

    __eq__(
        other
    )

Returns True if `self` is equivalent to `other`.

It first tries to convert `other` to `TensorShape`. `TypeError` is thrown
when the conversion fails. Otherwise, it compares each element in the
TensorShape dimensions.

- Two *Fully known* shapes, return True iff each element is equal.

    >>> t_a = tf.TensorShape([1,2])
    >>> a = [1, 2]
    >>> t_b = tf.TensorShape([1,2])
    >>> t_c = tf.TensorShape([1,2,3])
    >>> t_a.__eq__(a)
    True
    >>> t_a.__eq__(t_b)
    True
    >>> t_a.__eq__(t_c)
    False

- Two *Partially-known* shapes, return True iff each element is equal.

    >>> p_a = tf.TensorShape([1,None])
    >>> p_b = tf.TensorShape([1,None])
    >>> p_c = tf.TensorShape([2,None])
    >>> p_a.__eq__(p_b)
    True
    >>> t_a.__eq__(p_a)
    False
    >>> p_a.__eq__(p_c)
    False

- Two *Unknown shape*, return True.

    >>> unk_a = tf.TensorShape(None)
    >>> unk_b = tf.TensorShape(None)
    >>> unk_a.__eq__(unk_b)
    True
    >>> unk_a.__eq__(t_a)
    False

<br />

<br />

<br />

| Args ||
|---|---|
| `other` | A `TensorShape` or type that can be converted to `TensorShape`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| True if the dimensions are all equal. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| TypeError if `other` can not be converted to `TensorShape`. ||

<br />

### `__getitem__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L889-L937)

    __getitem__(
        key
    )

Returns the value of a dimension or a shape, depending on the key.

<br />

<br />

<br />

| Args ||
|---|---|
| `key` | If `key` is an integer, returns the dimension at that index; otherwise if `key` is a slice, returns a TensorShape whose dimensions are those selected by the slice from `self`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| An integer if `key` is an integer, or a `TensorShape` if `key` is a slice. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `key` is a slice and `self` is completely unknown and the step is set. |

<br />

### `__iter__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L879-L887)

    __iter__()

Returns `self.dims` if the rank is known, otherwise raises ValueError.

### `__len__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L866-L870)

    __len__()

Returns the rank of this shape, or raises ValueError if unspecified.

### `__nonzero__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L872-L874)

    __nonzero__()

Returns True if this shape contains non-zero information.

### `__radd__`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.10.1/tensorflow/python/framework/tensor_shape.py#L1001-L1004)

    __radd__(
        other
    )