Change dimension layout
Convert tensor layouts between conventions such as channel-first and channel-last.
PyTorch · Function
torch.permute
Reorders a tensor’s dimensions and returns a view of the original tensor. The dims argument specifies the desired axis order.
How it works
torch.permute returns a view of the input whose axes appear in the order specified by dims. The permutation changes the tensor shape and indexing interpretation without creating a separate data copy; dims can be supplied as a torch.Size, tuple, or list of integers.
Syntax
torch.permute(input, dims)Parameters
| Name | Type | Description |
|---|---|---|
input | Tensor | The tensor whose dimensions are to be reordered. |
dims | torch.Size, tuple of int, or list of int | The desired ordering of dimensions; a torch.Size, tuple of integers, or list of integers. |
Returns
A Tensor view of the original input with its dimensions permuted.
Key points
- The callable accepts an input tensor and a dimension-order specification, then returns a Tensor.
- The operation reorders axes through a view instead of describing a new independent tensor.
- dims expresses the target order of the input tensor's dimensions.
- The dimension order may be represented by torch.Size, a tuple of integers, or a list of integers.
- A three-dimensional tensor can be rearranged by passing the axis order (2, 0, 1).
- Applying that example permutation to shape (2, 3, 5) yields shape (5, 2, 3).
Common mistakes
- The result aliases the input because it is a view; modifying compatible elements through either tensor can affect the same underlying data.
Example: Reorder tensor dimensions
import torch
x = torch.randn(2, 3, 5)
y = torch.permute(x, (2, 0, 1))
assert x.shape == (2, 3, 5)
assert y.shape == (5, 2, 3)
assert y.storage().data_ptr() == x.storage().data_ptr()Reorders the three dimensions from (0, 1, 2) to (2, 0, 1), producing shape (5, 2, 3) while retaining shared storage.
When to use it
Match operator input conventions
Prepare multidimensional data for an operation that expects a particular axis order.
Create a lightweight view
Reinterpret axis order without immediately allocating a separate tensor.
Interview questions
QWhat does torch.permute do?
torch.permute(input, dims) returns a view of input with dimensions reordered according to dims. For an input shaped (2, 3, 5), the order (2, 0, 1) produces (5, 2, 3).
Follow-up: How would you avoid aliasing the input? Use a copying operation such as torch.permute_copy, which performs the permutation while creating fresh output tensors.
QWhat arguments does torch.permute accept?
input is the tensor being rearranged. dims specifies the desired dimension ordering and may be a torch.Size, tuple of integers, or list of integers.
Follow-up: What does the dimension sequence represent? It identifies the original axis used at each position in the result, rather than giving the new size values directly.
QWhy is torch.permute useful?
The function changes the dimension order while returning a view, so the output can have a different shape without duplicating the tensor's underlying data. The documented example changes (2, 3, 5) to (5, 2, 3).
Follow-up: When is a separate tensor preferable? Choose a copying variant when subsequent code requires independently allocated output storage rather than an aliasing view.
Related
torch.Tensor.permutetorch.permute_copy