NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #3276 most downloaded on PyPI
A dict[str, torch.Tensor] that behaves like one tensor.
Latest stable
0.15.5
Last release 10 days ago
05 Nov 2026
Release timing varies
gaps range from 8 days to 5 months
Nearly every release is documented
notes for 41 of 41 stable releases
Nothing withdrawn
no release was ever pulled
4 years old
47 releases · first in 2022
Drag across the ruler to compare, or tap a release to open it.
Upgrading needs torch 2.13 or later. A few announced removals take effect, and 58 deprecations, which take effect in 0.16 or 0.17, now warn; see Upgra…
TensorDict 0.15.0 contains the 581 pull requests merged since 0.14.0, 37 of which also shipped in the 0.14.1 to 0.14.3 patch releases:
torch.compile handles more tensordict code: 45 of 47 everyday patterns compile into one graph, against 41 in 0.14.3.Upgrading needs torch 2.13 or later. A few announced removals take effect, and 58 deprecations, which take effect in 0.16 or 0.17, now warn; see Upgrading from 0.14.
tensordict no longer has a C++ extension. Its only compiled code was 77 lines of pybind11 for the nested-key helpers unravel_key and unravel_key_list, which are now written in Python with fast paths for the common keys (#1916). A release is now one 690 KB py3-none-any wheel, where 0.14.3 had 24: one for each of 4 platforms and 6 Python builds, 3.10 to 3.14 and free-threaded 3.14 (#1917, #2219). tensordict therefore installs on any platform and Python version that PyTorch supports, and installing from source needs no C++ compiler, CMake or pybind11.
import tensordict._C still works, with a DeprecationWarning that names the public replacements; the module goes away in 0.17 (#2578).
We timed 0.15.0 against 0.14.3 on one core of an NVIDIA Grace CPU, with torch 2.14.1 and small tensors, so the numbers show tensordict's own overhead rather than the tensor math. Across 177 microbenchmarks, 0.15.0 is 1.77 times as fast on average (geometric mean), and across the 397 tests of the repository's benchmark suite, 1.83 times. These operations were chosen before any result was in:
| Operation | 0.14.3 (µs) | 0.15.0 (µs) | Speedup |
|---|---|---|---|
TensorDictModule forward |
157.3 | 27.59 | 6.0x |
td["a"] |
0.791 | 0.140 | 5.7x |
td.update(other), 16 keys |
31.28 | 5.855 | 5.2x |
list(td.keys(True)), 19 levels |
79.21 | 19.96 | 3.9x |
| read a tensorclass field | 0.973 | 0.266 | 3.6x |
td.to("cpu") when nothing moves |
58.50 | 26.76 | 2.2x |
td["a"] = x |
1.870 | 0.916 | 2.0x |
torch.stack of 8 tensordicts |
432.1 | 231.0 | 2.0x |
td["b", "c"] |
1.255 | 0.770 | 1.6x |
td + other, 16 nested leaves |
82.94 | 54.94 | 1.5x |
TensorDict(...), 16 leaves in 4 groups |
27.06 | 17.92 | 1.5x |
td[mask] |
74.77 | 52.91 | 1.5x |
td.apply(fn), 16 leaves |
45.22 | 31.97 | 1.4x |
TensorDict.load_memmap(path) |
2,313 | 1,779 | 1.3x |
| build a tensorclass | 9.421 | 7.410 | 1.3x |
with params.to_module(mlp) |
34.19 | 29.25 | 1.2x |
td.memmap(path), 16 leaves |
2,635 | 2,456 | 1.1x |
td[1:3] |
13.62 | 13.60 | 1.04x |
td[0] |
8.734 | 9.034 | 0.97x |
By area, construction, key access, set and update, to(device), tensordict.nn and to_module are about twice as fast, and saving and loading 1.9 times. Some workloads gain much more: writing a few rows into a NonTensorStack of strings takes O(rows) instead of O(size) (#2569), and indexing an h5 file reads only the selected rows (#1815). The changes behind these numbers are listed under Performance.
Six of the 177 microbenchmarks take 10% or more longer than in 0.14.3. Five are the nested-key helpers, which are now written in Python: unravel_key_list with mixed keys takes 1.5 times as long, and the others 1.1 to 1.2 times (#1916). The sixth is building TensorDictParams from a module, at 1.1 times.
We compiled 47 everyday patterns with fullgraph=True, among them construction, key access, update, apply, indexing, reshaping, stacking, tensorclasses and tensordict.nn modules. 45 compile into one graph without a break in 0.15.0, against 41 in 0.14.3. The two that still break, boolean-mask indexing and td * tensor, have workarounds in the new compile guide.
Several calls now compile with fullgraph=True:
td.to("cpu"), td.to(torch.float64) and td.permute(...);set_list_to_stack and the other option switches;A compiled function no longer recompiles when eager code elsewhere defines a new tensorclass or tensordict type. In a test of 30 such cases, 15 recompiled before and 2 do now (#2002). Reading td["key"] installs fewer guards, the checks that a compiled function runs before each call: 28 instead of 40 for a function that reads two entries (#2665). Tensordicts built under torch.compile keep their dim names (#2127).
CudaGraphModule no longer synchronizes the device before each replay, so a call no longer waits for work queued on other streams: with 20 ms of work on another stream, a call took 0.39 ms instead of 14 ms (#2000). A replay no longer changes the outputs of the previous call (#1999), and creating a module no longer removes tensordicts from the pytree registry of the process (#2312).
The new guide torch.compile, torch.func, torch.export, and CUDA graphs lists what breaks the graph or recompiles, and how to avoid it (#2019, #2208).
Each public operation now has one implementation, shared by every tensordict type: TensorDict, lazy stacks, memory-mapped tensordicts, h5 and zarr files, Redis-backed stores, sub-tensordicts, TypedTensorDict and TensorDictParams. Many methods now accept the same arguments and give the same results on every type, among them:
update, to, reshape, view and flatten;masked_fill and where;del_, rename_key_, popitem, get_at and indexed assignment;The series fixed more than 100 places where one type behaved differently from the others, with wrong results, ignored arguments or errors on valid calls. Each fix has a regression test. Most changes that could break working code warn with a FutureWarning in 0.15 and take effect in 0.17; the others are listed under Behavior changes. A new storage backend now implements a few documented private hooks instead of the whole public API.
pyright, and mypy when it follows tensordict's imports, read a tensorclass constructor from its fields (#2017). An IDE shows the fields when you call the class. A missing field, an unknown keyword or a value of the wrong type is an error before the code runs:
class Obs(TensorClass):
pos: torch.Tensor
label: str
Obs(pos=torch.zeros(3), batch_size=[3]) # error: argument missing for parameter "label"The type stubs now match the code, and tests keep them in sync (#1902, #2016). A tensorclass keeps its type through obs[0], obs.to("cpu"), obs.unbind(0), iteration and arithmetic, where pyright reported errors or Unknown in 0.14. td[0] and td[mask] are typed as TensorDict. One new strictness: a list or a NumPy array passed to a tensor field is a type error, although the constructor still casts it. TensorDict itself stays loosely typed: td["a"] is Any, and tensordict ships no py.typed marker yet, so mypy at its default settings skips the package.
td.pack() returns one (*batch_size, F) tensor with every leaf, and PackLayout.unpack rebuilds the tensordict from it (#2704).torch.abs(td), torch.clamp(td, 0, 1) and torch.sigmoid(td) work on tensordicts and tensorclasses, 77 in all (#2445).td.masked_select(mask, inplace=True) (#2447).__post_init__ works with lazy_stack, empty() and pad_sequence, and the class flag skip_post_init_on_rebuild runs the checks only when data comes in (#2707).set_interaction_type, set_skip_existing and set_composite_lp_aggregate take thread_local=True (#2589), and set_skip_existing(["key"]) skips a module only when all of its outputs are listed (#1771).TensorDict.load_memmap(path, mode="r") maps the files of a saved directory copy-on-write (#1821).from_h5(path, non_tensor_as_stack=True) and from_zarr(...) read a string column written by another tool, with one value per row, as rows (#2580).store[index] = 0.0 writes a scalar into the tensor entries of a TensorDictStore (#2018).isend and irecv take consolidated=True, to move a tensordict in one asynchronous message (#2585).Examples and details are under Features.
The docs use the PyTorch theme and have a new user guide (#2295). The guide covers:
TypedTensorDict, choosing a container, and tensordict.nn;The examples now run. On the guide and reference pages, 5 of 1,187 examples fail as written, all because they need CUDA, against 140 of 637 before; 251 of 252 docstring examples pass, against 41 of 182 (#1859 to #1866, #2203, #2295). The API reference lists each method once, grouped by task, and the README is rewritten (#2295, #2333, #2338).
The fixes are listed by area under Bug Fixes. Some of them fixed wrong results that came without an error:
add_, update_, copy_ and about 40 other in-place methods write to h5 and zarr files opened for writing (mode="r+") and to Redis stores; before, they left the data unchanged. On a read-only file they still write nothing, and now warn (#2347, #2596).lerp, addcmul and addcdiv pair the entries of a tensordict operand by key, as soft target-network updates expect; before, another key order mixed up the values (#2347, #2381).memmap and consolidate with several threads raise the error of a failed write; before, they returned a tensordict without that entry (#2474).__init__ runs. Since 0.12 it was skipped, and the fields got the raw arguments (#1977).TensorDictParams.to(dtype) keeps buffers as buffers; before, optimizers updated batch-norm statistics (#2055).pin_memory(inplace=True) pins the leaves of unlocked tensordicts, lazy stacks and tensorclasses, where it pinned nothing (#2666), and to("cpu") on CPU data no longer waits for queued GPU work (#2632).torch>=2.13.0a0, so that source and NGC builds of torch 2.13 qualify. Because of the a0, pip can also pick a torch nightly or release candidate from an index that serves them, even without --pre; pin torch if your pip configuration has such an index.importlib_metadata is no longer a dependency, typing_extensions is declared for Python 3.10, and the package metadata declares the MIT license, as the LICENSE file always has (#1859, #1899, #2122, #2219).tensordict<0.15.0, so pip and uv keep tensordict 0.14.x next to it. To use 0.15.0 with it, override that pin, for example with pip install --no-deps tensordict==0.15.0 after installing TorchRL. TorchRL 0.14.1's tests of specs, replay buffers, modules and objectives, about 20,000, give the same results with 0.15.0 as with 0.14.3, apart from one: it expects the log-probability that 0.14 stored for saturated tanh-squashed actions, which #2563 corrected.These can make code written for 0.14 fail or change its results without a warning first:
copy_at_(..., fast=None) and to_module(..., preserve_module_state=None) raise TypeError, as 0.14 announced. Pass True or False, or leave the argument out (#2216).import tensordict._tensordict, which has warned since 0.5, raises ModuleNotFoundError (#1898).tensordict.nn.make_functional and NormalParamWrapper. Use torch.func.functional_call and NormalParamExtractor (#1962).tensordict.utils.unravel_key_cpp, unravel_keys_cpp and unravel_key_list_cpp, the aliases of the C++ helpers, are gone; use unravel_key and unravel_key_list (#1916).from tensordict.utils import * give only public names, and import tensordict no longer imports tensordict.tabular (#1963, #1964, #1971).unravel_key(("a", 1)) and other tuples with a part that is not a key return (), in eager mode and under torch.compile; before, they returned the valid parts. ("a", 1) in td and unravel_key_list with such a key raise RuntimeError (#1903).__init__ runs (see above). A @tensorclass subclass that adds fields to a parent with a custom __init__ needs its own __init__. As in dataclasses, __post_init__ is not called after a custom __init__: call it from __init__ (#1977)._tensordict, from_tensordict or pack, raises AttributeError when the class is defined. Rename the field, or pass shadow=True (#2014, #2085, #2704).TruncatedNormal.entropy is a method, as in torch.distributions: call d.entropy() (#2356).view and reshape with a shape that does not fit raise RuntimeError, as torch does, instead of AssertionError (#2119).del obj.field on a tensorclass, obj.field is None instead of raising KeyError (#2318, #2357, #2477).load_memmap(directory, mode="r") maps the files copy-on-write, so in-place writes stay in memory. In 0.14, mode was ignored for directories (#1821).The 0.14.0 notes announced that load_memmap would default to allow_pickle=False in 0.15. That change moves to 0.16, so that checkpoints with pickled entries, such as TorchRL's, keep loading. Until then, loading a pickled entry without allow_pickle warns (#2223).
58 calls and settings now warn and keep their 0.14 behavior:
DeprecationWarning and take effect in 0.17.FutureWarning. Two take effect in 0.16: load_memmap defaults to allow_pickle=False, and a tuple of floats is stored as float32, like a list. The rest take effect in 0.17.TD_GET_DEFAULTS_TO_NONE=0, LIST_TO_STACK=0, CAPTURE_NONTENSOR_STACK=1, LAZY_LEGACY_OP=1 and EXCLUDE_TD_FROM_PYTREE=1 warn with a FutureWarning at import tensordict, so Python shows the warning by default (#2222, #2327).To find the uses in your code, run your tests with python -W error::DeprecationWarning -W error::FutureWarning -m pytest. This turns other libraries' warnings into errors too; tensordict's messages name the version, 0.16 or 0.17, in which the change happens.
| What now warns | What to do | Changes in | PRs |
|---|---|---|---|
TensorDictModule.device |
Read the device of the parameters or buffers you need: a module can hold several devices | 0.17 (removed) | #1770 |
The TypedTensorDict options autocast, nocast and tensor_only, which have no effect |
Drop them, or use a TensorClass, which implements them |
0.17 (removed) | #1882 |
set_lazy_legacy(True), the legacy lazy views of unsqueeze, squeeze, view, transpose and permute |
Use lazy_stack to build a lazy stack. set_lazy_legacy(False) keeps working |
0.17 (removed) | #1886 |
set_get_defaults_to_none(), get_defaults_to_none() |
Use td[key] to raise KeyError for a missing key |
0.17 (removed) | #1965 |
set_list_to_stack(False) |
Use td.set_non_tensor(key, value) to store a list as one value |
0.17 (removed) | #1965 |
set_capture_non_tensor_stack(True) |
Use NonTensorStack.data to get the one value of a stack of equal values |
0.17 (removed) | #1965 |
tensordict.implement_for, tensordict.is_compiling, tensordict.register_pytree_node and 11 other names that leaked from tensordict._pytree, and tensordict.is_batchedtensor |
Import them from where the warning says, for example pyvers.implement_for and torch.compiler.is_compiling |
0.17 (removed) | #1900, #1938, #1971 |
import tensordict._C |
Use tensordict.unravel_key and tensordict.unravel_key_list |
0.17 (removed) | #1916, #2578 |
21 helpers of tensordict.utils, such as cache, erase_cache, lock_blocked, prod, strtobool, unravel_keys, is_nested_key, is_seq_of_nested_key and json_dumps, and their re-exports in tensordict.tensordict |
Use math.prod, unravel_key or unravel_key_list, and isinstance(key, NestedKey). Most have no replacement |
0.17 (removed) | #1966 |
tensordict.nn internals: is_functional, ProbabilisticTensorDictModule(cache_dist=True), det_part, DETERMINISTIC_REGISTER, distributions_maps, StrEnum, set_tensor, set_tensor_dict, dispatch.get_source() and others |
Use get_dist_params() instead of det_part, and a deterministic_sample attribute on the distribution instead of the register. The others have no replacement |
0.17 (removed) | #1964 |
LazyStackedTensorDict.hook_in, hook_out, valid_keys(), get_nestedtensor(); MemoryMappedTensor.index, parent_shape, from_handler(); PersistentTensorDict.kwargs; pin_memory_(); load_(); to_local() on stores; NonTensorStack.from_nontensordata(); the tensordict.tabular module; tensordict.testing.MyDistData |
Use keys(), get(key, as_nested_tensor=True), pin_memory(inplace=True), load_memmap_(), to_tensordict(), NonTensorData.maybe_to_stack(), and TensorDict.from_pandas, to_csv and the other tabular methods |
0.17 (removed) | #1971 |
TensorClass.fields(), tc.extend(), from_tensordict(..., safe=...) |
Use dataclasses.fields(cls), build a new instance with lazy_stack or torch.cat, and drop safe |
0.17 (removed) | #2015 |
CompositeDistribution.entropy(aggregate_probabilities=...), which has no effect |
Use set_composite_lp_aggregate |
0.17 (removed) | #2276 |
update(..., ignore_lock=True), which never lifted the lock |
Use with td.unlock_(): td.update(...) |
0.17 (removed) | #2334 |
update_at_(index=...), update_at_(input_dict=...), update_at_(discard_idx_attr=...) and update_(input_dict=...), on tensordicts and tensorclasses |
Use idx=, input_dict_or_td=, and get_parent_tensordict().update_at_(...) |
0.17 (removed) | #2591, #2675 |
Arguments that are not fields, passed to a tensor_only tensorclass; keys that are not fields, written into a tensorclass by set_non_tensor, setdefault, create_nested, rename_key_ or update |
Pass and write only fields. These calls will raise AttributeError, as set() does |
0.17 (raises) | #2297, #2428 |
A tuple dim in max, min, prod, cummax, cummin and quantile, which reduce only its first dim |
Pass an int dim, as torch takes | 0.17 (removed) | #2427, #2530 |
LazyStackedTensorDict.from_dict(..., names=...) whose entries other than names[stack_dim] do not fit the members |
Pass stack_dim_name= |
0.17 (raises ValueError) |
#2454 |
| What now warns | What to do | Changes in | PRs |
|---|---|---|---|
load_memmap() that loads a pickled non-tensor field without allow_pickle |
Pass allow_pickle=True for data you trust, or allow_pickle=False to reject pickle now. Announced for 0.15 in 0.14.0, moved to 0.16 |
0.16 (default allow_pickle=False) |
#1763, #2223 |
Storing a tuple of floats, such as (0.0, 1.0), which becomes a float64 tensor where a list gives float32 |
Pass torch.tensor(value) or a list for the default dtype, or torch.tensor(value, dtype=torch.float64) or a NumPy array to keep float64 |
0.16 (dtype of torch.tensor(value)) |
#2702 |
A Python or NumPy bool, int or float written over a NonTensorData entry, which becomes a 0-d tensor |
Write torch.tensor(value) to keep the tensor, or NonTensorData(value) |
0.17 (stays NonTensorData) |
#2432, #2536 |
A list or a number written with set_at_ into a non-tensor entry, or with td[index] = value into a tensordict with non-tensor entries, which casts it to a tensor there |
Wrap the value in NonTensorData, or write into td.exclude(<non-tensor keys>)[index] to leave those entries unchanged |
0.17 | #2595 |
A dim outside the batch dims in repeat_interleave, flatten, torch.stack, maybe_dense_stack, torch.cat and lazy_stack, which is used on the dims of the leaves |
Pass a dim within the batch dims | 0.17 (raises IndexError) |
#2426, #2529 |
sum(dim=-1, reduce=True) and the other reductions with reduce=True and a negative dim, which count from the end of each leaf; amax and amin with a tuple dim, which reduce its first dim only |
Pass a non-negative dim | 0.17 (counted from the batch dims; every dim of the tuple) | #2427 |
from_any, and the conversions that call it on their values, on a torch.return_types result such as t.sort(1), keyed "0", "1" |
Pass it to from_namedtuple for its field names, or convert it with tuple() to keep the keys |
0.17 (field names) | #2407 |
Reading from an h5 PersistentTensorDict a string that tensordict wrote, which comes back as bytes |
Use value.decode() if isinstance(value, bytes) else value |
0.17 (str) |
#2418 |
NonTensorData.expand to a shape that torch.Tensor.expand rejects |
Pass a shape that the batch size expands to | 0.17 (raises RuntimeError) |
#2421 |
Tensorclass update_(source, keys_to_update=...), which writes the keys it leaves out, and update_at_(source, index) with a full-size source, which replaces every entry |
Pass a TensorDict source, or a source of the indexed shape |
0.17 (as TensorDict.update_ and update_at_) |
#2429 |
TensorClass.from_dict() that leaves a field with a declared default as None |
Pass the field | 0.17 (fills the default) | #2430 |
tree_map that drops the value returned for a NonTensorStack whose values are all equal |
No change needed; the result will keep the returned value | 0.17 | #2434 |
LazyStackedTensorDict.split with sizes along the stack dim that are negative or do not add up to the stack size |
Pass sizes that add up, as TensorDict.split requires |
0.17 (raises RuntimeError) |
#2437 |
flatten and permute arguments that a lazy stack accepts and TensorDict rejects |
Pass arguments that TensorDict accepts |
0.17 (raises ValueError) |
#2587 |
A CudaGraphModule replay of a tensordict function whose non-tensor arguments differ from the capture, which replays the captured values |
Pass the changing values as entries of the tensordict, or use one module per value | 0.17 (raises ValueError) |
#2438 |
to(device_or_dtype, batch_size=...) on a tensordict with nested tensordicts, which gives every nested tensordict that batch size and drops the names |
Call to(device_or_dtype), then set batch_size |
0.17 (nested batch sizes and names kept) | #2455 |
LazyStackedTensorDict(*tds, names=...), which ignores the names |
Pass stack_dim_name=, or set names on the stack |
0.17 (names applied) | #2572 |
LazyStackedTensorDict.from_dict(..., names=...) without batch_size, and TensorDict.from_list(..., names=...) with names that do not fit the result |
Pass a batch_size, or names that fit |
0.17 | #2454, #2460 |
Dense get(key, as_list=True) and get(key, as_nested_tensor=True), which return the stored tensor |
Drop the flag to keep the tensor | 0.17 (a list, or a nested tensor, as a lazy stack returns) | #2581 |
A names list of the wrong length that is accepted because of its None entries, and whose names are dropped |
Pass one name per batch dim | 0.17 (raises ValueError) |
#2677 |
TypedTensorDict.from_dict, from_any and the positional constructor when a required field is missing |
Pass the required fields | 0.17 (raises TypeError, as the keyword constructor) |
#2697 |
del_ of a missing key on TensorDictStore, LazyStackedTensorDictStore and zarr files, and rename_key_ of a missing key on the stores, which do nothing |
Check that the key exists first | 0.17 (raises KeyError) |
#2331 |
rename_key_ on a locked PersistentTensorDict or store, which renames |
Unlock it first | 0.17 (raises RuntimeError) |
#2424 |
add_, zero_ and the other in-place methods, and the write-back of with td.to(dtype), on an h5 or zarr file opened read-only, which leave the file unchanged |
Open the file with mode="r+" to write, or call to_tensordict() first to change a copy |
0.17 (raises) |
Note truncated.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
…and torch.compile . There are no new features or deprecations. Several fixes change behavior that was previously wrong; see "Behavior changes" below.
TensorDict 0.14.3 is a patch release with 24 bug fixes. They cover indexing with boolean masks and mixed advanced indices, memory-mapped loading and archives, TensorDictStore, UnbatchedTensor and non-tensor data, tensorclasses, tensordict.nn, and torch.compile. There are no new features or deprecations. Several fixes change behavior that was previously wrong; see "Behavior changes" below.
An upcoming tensordict release will require torch>=2.13 (#1830, discussed in #1828). tensordict currently declares no minimum torch version, so it can be installed next to torch releases that lack APIs it calls. Source builds and NGC containers of torch 2.13, which report versions such as 2.13.0a0+<sha>, will also meet the requirement.
tensordict 0.14.3 and earlier releases keep working with older torch. Once the requirement is released:
td[[True, False, True]], is now read as a boolean mask, as in torch. Before, the batch size of the result counted every entry and did not match its leaves (#1811).np.bool_, boolean NumPy arrays, nested lists, scalar True and False, N-D masks next to an Ellipsis, and None between advanced indices. Writes follow the same rules, so td[False] = value no longer overwrites every element (#1843).uint8 index tensor is now read as a mask in the batch size, as in torch, so td[uint8_mask] matches its leaves and writes through such a mask work (#1872).uint8 mask next to an Ellipsis takes as many dims as it has, so the batch size matches the entries (#1880).LazyStackedTensorDict with a boolean mask together with another advanced index now gives the same result as a dense TensorDict, for reads, writes and set_at_. Before, it raised a broadcasting error or returned wrong values (#1840).TensorDict.load_memmap(..., out=...), load_memmap_ and memmap_refresh_ now load nested containers on the requested device, or on out.device if no device is given. They remove keys that are not in the saved data, refresh NonTensorData and NonTensorStack entries, and load a tensorclass out in place (#1841).pack_memmap and archive save reject an output path inside the source directory, or one that links to a source file, so an archive can no longer include itself (#1812).SIGBUS and loses the data. Archives are now written to a temporary file and then moved into place, so a failed write leaves the old archive intact. Symlinks and permission bits of the destination are kept (#1813).TensorDictStore and LazyStackedTensorDictStore now bounds-check indices and normalize negative indices. Indexed writes convert and broadcast the value to the selected shape and dtype, as torch assignment does (#1814).LazyStackedTensorDictStore reads now return the right values for multi-dimensional indices such as (0, slice(None)), (tensor, int), None or an Ellipsis. store[..., 1] now selects batch dimension 1 (#1819).get_at, set_at_ and indexed writes of both stores read a list of bools as a boolean mask (#1842).TypeError (#1858).get_at and masked writes of per-element non-tensor entries of TensorDictStore follow the index. Before, most indices returned the whole entry, get_at raised KeyError, and masked writes changed the wrong elements (#1856, fixes #1833).close() now closes the event loop of the store. Before, using a closed store hung, for example in repr(store) (#1871).memmap(), memmap_(), save() and consolidate() raise NotImplementedError for a tensordict that contains an UnbatchedTensor, naming the entry. Before, they turned the entry into a plain tensor that no longer matched the batch size, so indexing the result returned wrong values (#1847, fixes #1846).vmap over UnbatchedTensor views no longer fails on torch 2.13 and older, which use a fallback implementation of UnbatchedTensor (#1792, #1875).consolidate() no longer locks the non-tensor entries of its source, so a later masked update such as source.where(mask, other, out=source) works (#1790).is_leaf works when a child is a TypedTensorDict, and wrapping a typed value after a mutation no longer causes a graph break under torch.compile on recent PyTorch nightly builds (#1789).to_module with preserve_module_state=True, the default since 0.14, no longer wraps leaves that require grad in a new nn.Parameter, so gradients reach the tensors that were passed in. Vmapping over to_module also works under torch.compile(fullgraph=True) (#1845, fixes #1844).TensorClassModuleBase.as_td_module() works when the input or output tensorclass has string annotations, as with from __future__ import annotations, or optional fields. It raised TypeError (#1849, fixes #1848).ProbabilisticTensorDictModule in MEAN mode falls back to the empirical mean when a distribution's mean raises NotImplementedError, as TorchRL's TanhNormal does (#1827, fixes #1152).TensorClass field named after a TensorClass method or property, such as sum or shape, raises the reserved-name error unless shadow is set, whatever the field order. With shadow, such fields work in both the subclass and the decorator form. Before, the subclass form raised an unrelated TypeError, and attribute access returned the method instead of the stored value (#1851, fixes #1850).TensorDict.cummax(reduce=True) now returns a torch.return_types.cummax, as documented, instead of raising AttributeError (#1853).These fixes can change the behavior of existing code:
load_memmap(out=...), load_memmap_ and memmap_refresh_ remove keys of the target that are not in the saved data. load_memmap raises ValueError when device differs from out.device, or when a lazy stack is loaded into a stack of a different length (#1841).memmap(), memmap_(), save() and consolidate() raise NotImplementedError for tensordicts that contain an UnbatchedTensor (#1847).to_module(..., preserve_module_state=True), leaves that require grad are stored in module._parameters as they are, not as a new nn.Parameter, and a leaf that is not a Parameter keeps requires_grad=True (#1845).IndexError for out-of-range indices and for masks of the wrong length. Writes through a list or tensor index with a different dtype raise RuntimeError, as index_put_ does (#1814).NonTensorStack. An index that a non-tensor entry cannot take raises TypeError before anything is written (#1856).shadow, a TensorClass field named after a method or property returns the stored value from attribute access and get, instead of the method (#1851).close() raises RuntimeError: Event loop is closed instead of hanging (#1871).pip install tensordict==0.14.3Thanks to @jayzuccarelli (first contribution), @javierdejesusda, @peterdsharpe, and @vmoens for their contributions to this release.
Full Changelog: v0.14.2...v0.14.3
…and CUDA graph replay. No new public APIs, breaking changes, or deprecations are introduced.
TensorDict 0.14.2 is a patch release correcting compiled shallow copies, non-tensor concatenation, and CUDA graph replay. No new public APIs, breaking changes, or deprecations are introduced.
Install after publication: pip install tensordict==0.14.2
Thanks to @vmoens.
…tensorclass deserialization. It contains no breaking changes, new features, or deprecations.
TensorDict 0.14.1 is a focused patch release with correctness fixes for module metadata, lazy and non-tensor indexing, and frozen tensorclass deserialization. It contains no breaking changes, new features, or deprecations.
TensorDictModuleBase subclasses, including their child modules and input and output keys (#1767).LazyStackedTensorDict (#1772).TensorDictModule output-key metadata synchronized when out_keys is reassigned (#1773).NonTensorStack return independent entries, preventing indexed results from mutating their source or one another (#1778).pip install tensordict==0.14.1Thanks to @priba, @gtnv, @simonschlaepfer, and @vmoens for their contributions to this release.
Full Changelog: v0.14.0...v0.14.1
TensorDict 0.14.0 introduces Zarr-backed persistent storage, portable single-file memory-mapped archives, and direct autograd through TensorDict.backw
TensorDict 0.14.0 introduces Zarr-backed persistent storage, portable single-file memory-mapped archives, and direct autograd through TensorDict.backward(). It also improves serialization performance, distributed point-to-point operations, UnbatchedTensor interoperability, and memmap correctness and security.
TensorDict.to_module() now preserves existing module parameter and buffer registrations by default. Pass preserve_module_state=False to retain the previous replacement behavior (#1720).TensorDict.copy_at_() now uses its optimized tensor-only path by default. Pass fast=False to retain the previous update_at_() fallback behavior (#1691).allow_pickle across load and refresh APIs. In 0.14, omitting it still loads pickled non-tensor data with a warning; the default will become allow_pickle=False in 0.15. Pass True only for trusted artifacts or False to reject pickle now (#1763).PersistentTensorDict storage through to_zarr(), from_zarr(), and compatible store backends (#1754)..tdz archives for memory-mapped TensorDicts, including lazy loading, subpath access, compression, writable mappings, and pack/unpack utilities (#1735).TensorDict.backward() for differentiating all compatible tensor leaves in one autograd operation (#1733).group_dst and group_src for distributed send and receive operations (#1739).vmap support and Python scalar conversions for UnbatchedTensor (#1729, #1728).NonTensorStack entries in contiguous() (#1746).TensorDictParams.load_state_dict(strict=False) to skip missing submodules (#1734)._SubTensorDict memmap round trips (#1736).UnbatchedTensor stack metadata (#1731, #1730).Thanks to @peterdsharpe, and @javierdejesusda, both first-time contributors!
Full Changelog: v0.13.0...v0.14.0
TensorDict 0.13.0 adds new data import/export capabilities, broader in-place shape-changing operations, and several torch.compile reliability improvem
TensorDict 0.13.0 adds new data import/export capabilities, broader in-place shape-changing operations, and several torch.compile reliability improvements. This release also improves memmap/file-backed workflows, TensorClass behavior under compile/export, to_module() state preservation migration, and release infrastructure for CPU-only TensorDict wheels.
robust_key now defaults to robust filesystem-safe key encoding for memmap save/load APIs (#1717). Passing robust_key=False keeps the legacy filename behavior for existing legacy memmap directories.robust_key FutureWarning targeting v0.12 has been enacted by making robust encoding the default (#1717).TensorDict.to_module() now warns when writing a plain tensor over an existing nn.Parameter would deregister it from module.state_dict(); pass preserve_module_state=False to keep the v0.13 behavior or preserve_module_state=True to opt in to the v0.14 default (#1720).copy_at_(..., fast=None) fallback warning remains active; the default is scheduled to change to fast=True in v0.14.**kwargs support to update() and update_() (#1677).ProbabilisticTensorDictModule (#1689).canonical=True support to contiguous() (#1698).inplace=True support to pad() to reduce peak memory (#1706).inplace=True support to gather, repeat, repeat_interleave, roll, reshape, flatten, unflatten, and contiguous (#1707).preserve_module_state to TensorDict.to_module() so existing nn.Parameter and buffer registrations can be preserved when loading TensorDict leaves into modules (#1720).unravel_keys inconsistency that prevented torch.compile in some cases (#1674).ragged_idx handling for consolidated tensors (#1675).MetaData (#1697).SymInt values in _parse_batch_size and storing batch dimensions in pytree context (#1704).__post_init__ and field default application under torch.compile (#1709).TensorDict.copy_at_ (#1691).frozenset and dict_keys (#1703).clone(recurse=False) via cached schema.Thanks to all contributors to this release, including first-time contributors @mathieuorhan, @arpitjain099, and @felixmaximilian.
Full Changelog: v0.12.0...v0.13.0
TensorDict 0.12.4 is a bugfix-only release. It contains no new features.
TensorDict 0.12.4 is a bugfix-only release. It contains no new features.
SymInt batch sizes and preserved batch-dimension metadata in pytree context (#1704).__post_init__, field defaults, default factories, and omitted None defaults are applied correctly under torch.compile (#1709).non_blocking handling (#1711).frozenset - dict_keys now that it is traceable in newer PyTorch versions.[BugFix] Fix auto batch size with MetaData by @vmoens in #1697
TensorDictBase.auto_batch_size_() no longer collapses the batch size to an
empty shape when a TensorDict contains scalar MetaData / NonTensorData
(pass-through) entries. Previously a single scalar metadata leaf forced the
inferred batch size down to torch.Size([]), ignoring real tensor leaves.
Full Changelog: v0.12.2...v0.12.3
Patch release with a bug fix for consolidated nested tensors.
Patch release with a bug fix for consolidated nested tensors.
_ragged_idx loss during consolidation of nested tensors, which caused numerical incorrectness when the nested tensor had more than 2 dimensions and ragged_idx != 1 (#1675)pip install tensordict==0.12.2Full Changelog: v0.12.1...v0.12.2
Patch release with a torch.compile bug fix.
Patch release with a torch.compile bug fix.
unravel_keys inconsistency that prevented torch.compile from working correctly when called with a single key (#1674)pip install tensordict==0.12.1TensorDict v0.12.0 introduces TypedTensorDict for schema-enforced tensor dictionaries, a full distributed collectives suite (broadcast, all_reduce, al
TensorDict v0.12.0 introduces TypedTensorDict for schema-enforced tensor dictionaries, a full distributed collectives suite (broadcast, all_reduce, all_gather, scatter), TensorDictStore with Redis/Dragonfly/KeyDB backends, and major torch.compile and performance improvements. The UnbatchedTensor has been rewritten as a proper tensor subclass, and state_dict handling has been overhauled for consistency.
UnbatchedTensor is now a __torch_dispatch__-based tensor subclass (was previously a wrapper) (#1638, #1648)state_dict is now flat by default, with auto-detection in load_state_dict for backwards compatibilitystate_dict now uses logical keystorch.compile support (#1657, #1659, #1660, #1662, #1663)broadcast, all_reduce, all_gather, scatter, consolidated send/recv and init_remote/from_remote_init with UCXX transport support (#1611)set_printoptions: Configurable TensorDict repr with verbose mode (#1654, #1655, #1665)torch.func support: jacrev, jacfwd, and hessian now work with TensorDict (#1613)vmap with unbatched data: TensorDicts containing unbatched tensors can now be vmapped (#1625)TensorClass.select(as_tensordict=...) parameter (#1544)TensorDictBase.is_non_tensor(key) for consistent non-tensor key detectionHigherOrderOperator support in __torch_function__ (#1668)td[key] = [] handling (#1666)UnbatchedTensor.tolist() (#1664)UnbatchedTensor CUDA pickling for multiprocessing (#1656)UnbatchedTensor indexing without batch dim, GPU failures, getitem/stack (#1607, #1626, #1633)replace() recompiles under torch.compile (#1605)auto_batch_size regression with NonTensorStack (#1609)NonTensorData positional args causing graph breaks under torch.compile (#1630)state_dict error messages, params forwarding, detachpybind11>=2.13 for Python 3.13 compatibilityTensorDict.__init__ by bypassing set() dispatch chain (#1551)TensorClass.__init__ by bypassing __setattr__ and dataclass __init__ (#1552)torch.cuda.synchronize() in .to() (#1545)torch.compile (#1636)Removed deprecated features scheduled for v0.11 ( #1526 ):
This release brings Python 3.14 support (including free-threaded mode), drops Python 3.9, adds extensive torch.compile compatibility improvements, introduces new tensor manipulation methods, and expands NPU device support.
pad_sequence device parameter removed (deprecated since v0.5)MemoryMappedTensor._tensor property now raises RuntimeError - use the tensor directly since it's a tensor subclassset_lazy_legacy now raises RuntimeErrorlock, unlock, rename_key (without trailing underscore) now raise RuntimeError - use lock_, unlock_, rename_key_ insteadPython 3.14 and free-threading support (#1481, #1438) - Fixed race conditions in value caching that caused segfaults under free-threaded Python (PYTHON_GIL=0). The library now declares it does not require the GIL.
TensorClassModuleBase (#1473) - New base class for type-safe PyTorch modules that operate on TensorClass instances. Provides compile-time type checking, automatic TensorDict conversion via as_td_module(), nested TensorClass support, and ONNX export compatibility.
New tensor manipulation methods - Added several torch-compatible operations:
td.movedim() (#1504)td.swapaxes()td.flip(), td.fliplr()td.roll()td.rot90()td.narrow(), td.tile(), td.broadcast_to()td.atleast_Nd()td.mod()Quantiles support (#1450) - Added quantile computation for TensorDicts
Context manager for td.to() (#1448) - td.to() can now be used as a context manager for temporary device transfers
key_transform for reduce ops (#1451) - Added key transformation support for reduction operations
selected_out_keys for ProbabilisticTensorDictSequential (#1497) - Added ability to specify which output keys to keep
Extended NPU support (#1471, #1460) - Expanded NPU device support across more use cases previously limited to CUDA
torch.compile compatibility fixes:
Robust key setting with memmap tensordicts (#1443) - Major fix for handling key operations with memory-mapped tensordicts
Saving and loading metadata (#1444) - Fixed memmap + serialization issues with MetaData typed objects
tensordict.cat preserves TensorClass (#1456)
Names propagation for nested TensorDicts (#1520) - Fixed names propagation with extra batch dimensions
Device mismatch in CUDA/NPU scenarios (#1439) - Fixed "expect all tensors on the same device" errors
Nested lazy stacks handling (#1461) - Fixed as_list and other operations with nested lazy stacks
PyTorch version compatibility (#1498, #1499, #1437) - Various fixes for compatibility with older PyTorch versions
🔄 Deprecations and Breaking Changes
We are excited to announce the release of TensorDict 0.10.0! This release includes significant improvements to type annotations, new features for metadata handling, enhanced tensor operations, and numerous bug fixes that improve the overall stability and usability of the library.
to_struct_array now supports string data types (#1410)to_mds method creates an MDS dataset on your favourite location -- no more painful columns definition etc (#1426).grad function (#1417)to_struct_array functionality to handle string data typestensor_split operation to match PyTorch tensor API__all__ declarations across all modules for better IDE support and import control@overload for methods that have a reduce arg (#1427): Added proper type overloads for methods with reduce parameters__getitem__ (#1402): Improved type annotations for indexing operationsTensorDictModuleWrapper forward (#1415): Fixed forward pass in TensorDictModuleWrapperrepeat_interleave to properly support tensor argumentsset_list_to_stack with proper deprecation warnings for the old APISpecial thanks to all the contributors who made this release possible:
For comprehensive documentation, tutorials, and examples, visit:
For a complete list of changes, see the full changelog.
If you encounter any issues, please report them on our GitHub Issues page.
This minor releases brings the following improvements and bug fixes:
This minor releases brings the following improvements and bug fixes:
Full Changelog: https://github.com/pytorch/tensordict/compare/v0.9.0...v0.9.1
One column per quarter.