●Change8

Migrating to Datasets 4.0.0

Version 4.0.0 introduces 3 breaking changes. This guide details how to update your code.

Released: 7/9/2025

3
Breaking Changes
4
Migration Steps
10
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

IterableDataset.push_to_hubDataset.push_to_hubColumnIterableColumndatasets.Sequencedatasets.ListtorchcodecsoundfiledecordDataset.map

Breaking Changes

●Issue #1

Removed scripts entirely; `trust_remote_code` is no longer supported.

●Issue #2

Torchcodec replaces `soundfile` for audio decoding and `decord` for video decoding.

●Issue #3

The `Sequence` type is replaced by `List`. `Sequence` is now a utility that returns a `List` or a `dict` depending on the subfeature structure, instead of being a feature type itself.

Migration Steps

  1. 1
    If you relied on `trust_remote_code=True`, you must now handle code execution locally, as this option is removed.
  2. 2
    Replace usage of `Sequence(Value("string"))` with `List(Value("string"))` in feature definitions.
  3. 3
    If using audio/video decoding, note that `torchcodec` is now the default backend, requiring `torch>=2.7.0` and FFmpeg >= 4. Windows support for torchcodec decoding is pending.
  4. 4
    If you were using `soundfile` or `decord` directly for decoding, be aware they are replaced by `torchcodec`.

Release Summary

This release introduces significant new features like `push_to_hub` for streaming datasets and lazy column access via the new `Column` object. It also mandates a migration away from the legacy `Sequence` type to the new `List` type and updates audio/video decoding backends to use `torchcodec`.

Need More Details?

View the full release notes and all changes for Datasets 4.0.0.

View Full Changelog