<!-- # hard line break macro for HTML -->

# fiftyone.utils.lerobot

LeRobotDataset v3 import and asset resolution utilities.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Exceptions:**

| [`UnsupportedLeRobotVersionError`](#fiftyone.utils.lerobot.UnsupportedLeRobotVersionError)            | The referenced LeRobot source declares an unsupported version.   |
|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`UnsupportedLeRobotExportModeError`](#fiftyone.utils.lerobot.UnsupportedLeRobotExportModeError)(...) | The requested LeRobot export media mode is unsupported.          |

**Classes:**

| [`LeRobotEpisodeReference`](#fiftyone.utils.lerobot.LeRobotEpisodeReference)(\*args, \*\*kwargs)   | One episode of a LeRobotDataset v3 source.                                               |
|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`LeRobotSource`](#fiftyone.utils.lerobot.LeRobotSource)(id, root, info)                           | One LeRobot source: the id its dataset files it under, where it is and what it declares. |
| [`LeRobotDatasetImporter`](#fiftyone.utils.lerobot.LeRobotDatasetImporter)(dataset_dir[, ...])     | Imports logical episodes from a LeRobotDataset v3 source.                                |

### *exception* fiftyone.utils.lerobot.UnsupportedLeRobotVersionError

Bases: `MediaReferenceError`

The referenced LeRobot source declares an unsupported version.

**Methods:**

| [`add_note`](#fiftyone.utils.lerobot.UnsupportedLeRobotVersionError.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.utils.lerobot.UnsupportedLeRobotVersionError.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.utils.lerobot.UnsupportedLeRobotVersionError.args)   |    |
|-------------------------------------------------------------------------|----|

#### add_note(object,)

Exception.add_note(note) –
add a note to the exception

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### *exception* fiftyone.utils.lerobot.UnsupportedLeRobotExportModeError(export_media, suggestion)

Bases: `UnsupportedMediaReferenceOperation`

The requested LeRobot export media mode is unsupported.

**Methods:**

| [`add_note`](#fiftyone.utils.lerobot.UnsupportedLeRobotExportModeError.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.utils.lerobot.UnsupportedLeRobotExportModeError.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.utils.lerobot.UnsupportedLeRobotExportModeError.args)   |    |
|----------------------------------------------------------------------------|----|

#### add_note(object,)

Exception.add_note(note) –
add a note to the exception

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### *class* fiftyone.utils.lerobot.LeRobotEpisodeReference(\*args, \*\*kwargs)

Bases: [`MediaReference`](fiftyone.core.media_reference.md#fiftyone.core.media_reference.MediaReference)

One episode of a LeRobotDataset v3 source.

The coordinates are the episode’s own: an episode is a row range of the
source’s data shard and a time window of each of its camera videos, all
of which it shares with the other episodes recorded alongside it.

* **Parameters:**
  * **key** – `<media source id>/<episode index>`
  * **data** – `[chunk index, file index, first row, last row]` of the
    episode’s rows in the source’s tabular data
  * **videos** – the episode’s window in each camera’s video, keyed by camera,
    as `[chunk index, file index, from timestamp, to timestamp]`
  * **tasks** – the tasks the episode demonstrates

**Attributes:**

| [`data`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.data)                 | A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.   |
|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| [`videos`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.videos)             | A dictionary field that wraps a standard Python dictionary.                                                                    |
| [`tasks`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.tasks)               | A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.   |
| [`episode`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.episode)           | The zero-based episode index within the source.                                                                                |
| [`display_name`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.display_name) | A human-readable name for the referenced media.                                                                                |
| [`STRICT`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.STRICT)             |                                                                                                                                |
| [`field_names`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.field_names)   | An ordered tuple of the public fields of this document.                                                                        |
| [`key`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.key)                   | A unicode string field.                                                                                                        |
| [`media_type`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.media_type)     | The media type of every reference-backed sample.                                                                               |
| [`source_id`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.source_id)       | The id of the media source on the owning dataset.                                                                              |

**Methods:**

| [`key_of`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.key_of)(source_id, episode)                       | The key naming one episode of a source.                                                                  |
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| [`episode_of`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.episode_of)(key)                              | The episode index a reference key names.                                                                 |
| [`of`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.of)(source_id, episode, \*\*coordinates)              | Builds a reference to one episode of a source.                                                           |
| [`clean`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.clean)()                                           | Hook for doing document level data cleaning (usually validation or assignment) before validation is run. |
| [`clear_field`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.clear_field)(field_name)                     | Clears the field from the document.                                                                      |
| [`copy`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.copy)()                                             | Returns a deep copy of the document.                                                                     |
| [`fancy_repr`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.fancy_repr)([class_name, select_fields, ...]) | Generates a customizable string representation of the document.                                          |
| [`field_to_mongo`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.field_to_mongo)(field_name)               |                                                                                                          |
| [`field_to_python`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.field_to_python)(field_name, value)      |                                                                                                          |
| [`from_dict`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.from_dict)(d[, extended])                      | Loads the document from a BSON/JSON dictionary.                                                          |
| [`from_json`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.from_json)(s)                                  | Loads the document from a JSON string.                                                                   |
| [`get_field`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.get_field)(field_name)                         | Gets the field of the document.                                                                          |
| [`get_text_score`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.get_text_score)()                         | Get text score from text query                                                                           |
| [`has_field`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.has_field)(field_name)                         | Determines whether the document has a field of the given name.                                           |
| [`iter_fields`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.iter_fields)()                               | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                 |
| [`merge`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.merge)(doc[, merge_lists, merge_dicts, overwrite]) | Merges the contents of the given document into this document.                                            |
| [`set_field`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.set_field)(field_name, value[, create])        | Sets the value of a field of the document.                                                               |
| [`source_of`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.source_of)(key)                                | The media source a reference key names.                                                                  |
| [`to_dict`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.to_dict)([extended])                             | Serializes this document to a BSON/JSON dictionary.                                                      |
| [`to_json`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.to_json)([pretty_print])                         | Serializes the document to a JSON string.                                                                |
| [`to_mongo`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.to_mongo)(\*args, \*\*kwargs)                   | Return as SON data ready for use with MongoDB.                                                           |
| [`validate`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.validate)([clean])                              | Ensure that all fields' values are valid and that required fields are present.                           |

**Classes:**

| [`my_metaclass`](#fiftyone.utils.lerobot.LeRobotEpisodeReference.my_metaclass)   |    |
|----------------------------------------------------------------------------------|----|

#### data

A list field that wraps a standard `Field`, allowing multiple
instances of the field to be stored as a list in the database.

If this field is not set, its default value is `[]`.

* **Parameters:**
  * **field** (*None*) – an optional `Field` instance describing the
    type of the list elements
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### videos

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is `{}`.

* **Parameters:**
  * **field** (*None*) – an optional `Field` instance describing the type
    of the values in the dict
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### tasks

A list field that wraps a standard `Field`, allowing multiple
instances of the field to be stored as a list in the database.

If this field is not set, its default value is `[]`.

* **Parameters:**
  * **field** (*None*) – an optional `Field` instance describing the
    type of the list elements
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### *static* key_of(source_id, episode)

The key naming one episode of a source.

* **Parameters:**
  * **source_id** – the id of the media source on the owning dataset
  * **episode** – the zero-based episode index within the source
* **Returns:**
  the key

#### *static* episode_of(key)

The episode index a reference key names.

* **Parameters:**
  **key** – a LeRobot episode reference key
* **Returns:**
  the zero-based episode index

#### *classmethod* of(source_id, episode, \*\*coordinates)

Builds a reference to one episode of a source.

* **Parameters:**
  * **source_id** – the id of the media source on the owning dataset
  * **episode** – the zero-based episode index within the source
  * **\*\*coordinates** – the episode’s stored coordinates
* **Returns:**
  a [`LeRobotEpisodeReference`](#fiftyone.utils.lerobot.LeRobotEpisodeReference)

#### *property* episode

The zero-based episode index within the source.

#### *property* display_name

A human-readable name for the referenced media.

#### STRICT *= False*

#### clean()

Hook for doing document level data cleaning (usually validation or assignment)
before validation is run.

Any ValidationError raised by this method will not be associated with
a particular field; it will have a special-case association with the
field defined by NON_FIELD_ERRORS.

#### clear_field(field_name)

Clears the field from the document.

* **Parameters:**
  **field_name** – the field name
* **Raises:**
  **ValueError** – if the field does not exist

#### copy()

Returns a deep copy of the document.

* **Returns:**
  a `SerializableDocument`

#### fancy_repr(class_name=None, select_fields=None, exclude_fields=None, \*\*kwargs)

Generates a customizable string representation of the document.

* **Parameters:**
  * **class_name** (*None*) – optional class name to use
  * **select_fields** (*None*) – iterable of field names to restrict to
  * **exclude_fields** (*None*) – iterable of field names to exclude
  * **\*\*kwargs** – additional key-value pairs to include in the string
    representation
* **Returns:**
  a string representation of the document

#### *property* field_names

An ordered tuple of the public fields of this document.

#### field_to_mongo(field_name)

#### field_to_python(field_name, value)

#### *classmethod* from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

* **Parameters:**
  * **d** – a dictionary
  * **extended** (*False*) – whether the input dictionary may contain
    serialized extended JSON constructs
* **Returns:**
  a `SerializableDocument`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

* **Returns:**
  a `SerializableDocument`

#### get_field(field_name)

Gets the field of the document.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  the field value
* **Raises:**
  **AttributeError** – if the field does not exist

#### get_text_score()

Get text score from text query

#### has_field(field_name)

Determines whether the document has a field of the given name.

* **Parameters:**
  **field_name** – the field name
* **Returns:**
  True/False

#### iter_fields()

Returns an iterator over the `(name, value)` pairs of the
public fields of the document.

* **Returns:**
  an iterator that emits `(name, value)` tuples

#### key

A unicode string field.

* **Parameters:**
  * **description** (*None*) – an optional description
  * **info** (*None*) – an optional info dict
  * **read_only** (*False*) – whether the field is read-only
  * **created_at** (*None*) – the datetime the field was created

#### *property* media_type

The media type of every reference-backed sample. A sample of one
modality names its media by filepath; a reference is what multimodal
media is named by.

#### merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

* **Parameters:**
  * **doc** – a `SerializableDocument` of same type as this document
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields rather than treating the list as a single value
  * **merge_dicts** (*True*) – whether to recursively merge the contents of
    top-level dict fields rather than treating the dict as a single
    value
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields

#### my_metaclass

alias of `DocumentMetaclass`

#### set_field(field_name, value, create=True)

Sets the value of a field of the document.

* **Parameters:**
  * **field_name** – the field name
  * **value** – the field value
  * **create** (*True*) – whether to create the field if it does not exist
* **Raises:**
  **ValueError** – if `field_name` is not an allowed field name or does
      not exist and `create == False`

#### *property* source_id

The id of the media source on the owning dataset.

#### *static* source_of(key)

The media source a reference key names.

* **Parameters:**
  **key** – a media reference key
* **Returns:**
  the source id

#### to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

* **Parameters:**
  **extended** (*False*) – whether to serialize extended JSON constructs
  such as ObjectIDs, Binary, etc. into JSON format
* **Returns:**
  a dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

* **Parameters:**
  **pretty_print** (*False*) – whether to render the JSON in human readable
  format with newlines and indentations
* **Returns:**
  a JSON string

#### to_mongo(\*args, \*\*kwargs)

Return as SON data ready for use with MongoDB.

#### validate(clean=True)

Ensure that all fields’ values are valid and that required fields
are present.

Raises `ValidationError` if any of the fields’ values are found
to be invalid.

### *class* fiftyone.utils.lerobot.LeRobotSource(id: str, root: str, info: dict)

Bases: `object`

One LeRobot source: the id its dataset files it under, where it is
and what it declares.

**Attributes:**

| [`id`](#fiftyone.utils.lerobot.LeRobotSource.id)     |    |
|------------------------------------------------------|----|
| [`root`](#fiftyone.utils.lerobot.LeRobotSource.root) |    |
| [`info`](#fiftyone.utils.lerobot.LeRobotSource.info) |    |

#### id *: str*

#### root *: str*

#### info *: dict*

### *class* fiftyone.utils.lerobot.LeRobotDatasetImporter(dataset_dir, episodes=None, shuffle=False, seed=None, max_samples=None)

Bases: [`GenericSampleDatasetImporter`](fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.GenericSampleDatasetImporter)

Imports logical episodes from a LeRobotDataset v3 source.

Reads `meta/info.json` and the episode-metadata shards, nothing else:
no data shard, video, or statistics file is opened. Samples are produced
one shard at a time, each carrying only its episode’s key; the dataset
records the source once.

An episode’s sample names its media by `media_reference` rather than
`filepath`, and a reference only resolves through a source the dataset
records. Build these datasets from a directory, not by adding samples:

```default
import fiftyone as fo
import fiftyone.types as fot

# one source, one dataset
dataset = fo.Dataset.from_dir(
    dataset_dir="/data/lerobot/pick-place",
    dataset_type=fot.LeRobotDataset,
)

# more sources into the same dataset; each records itself as it
# arrives, so every episode stays resolvable
dataset.add_dir(
    dataset_dir="/data/lerobot/sort-nuts",
    dataset_type=fot.LeRobotDataset,
)
```

`add_samples` cannot be used to introduce a new source: a sample whose
reference names a source the dataset does not record is refused, because
nothing would say where its bytes are.

* **Parameters:**
  * **dataset_dir** – the LeRobot dataset root, local or remote
  * **episodes** (*None*) – optional episode indexes to import
  * **shuffle** (*False*) – whether to randomly shuffle selected episodes
  * **seed** (*None*) – a random seed to use when shuffling
  * **max_samples** (*None*) – a maximum number of episodes to import

**Attributes:**

| [`has_dataset_info`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.has_dataset_info)               | Whether this importer produces a dataset info dictionary.   |
|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| [`has_sample_field_schema`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.has_sample_field_schema) | Whether this importer produces a sample field schema.       |

**Methods:**

| [`get_sample_field_schema`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.get_sample_field_schema)()   | Returns a dictionary describing the field schema of the samples loaded by this importer.                                        |
|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`get_dataset_info`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.get_dataset_info)()                 | Returns the dataset info for the dataset.                                                                                       |
| [`get_media_sources`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.get_media_sources)()               | The media source the importing dataset records before any sample is added, so every sample's reference resolves from the start. |
| [`setup`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.setup)()                                       | Performs any necessary setup before importing the first sample in the dataset.                                                  |
| [`close`](#fiftyone.utils.lerobot.LeRobotDatasetImporter.close)(\*args)                                 | Performs any necessary actions after the last sample has been imported.                                                         |

#### *property* has_dataset_info

Whether this importer produces a dataset info dictionary.

#### *property* has_sample_field_schema

Whether this importer produces a sample field schema.

#### get_sample_field_schema()

Returns a dictionary describing the field schema of the samples
loaded by this importer.

* **Returns:**
  a dict mapping field names to [`fiftyone.core.fields.Field`](fiftyone.core.fields.md#fiftyone.core.fields.Field)
  instances or `str(field)` representations of them

#### get_dataset_info()

Returns the dataset info for the dataset.

By convention, this method should be called after all samples in the
dataset have been imported.

* **Returns:**
  a dict of dataset info

#### get_media_sources()

The media source the importing dataset records before any sample
is added, so every sample’s reference resolves from the start.

#### setup()

Performs any necessary setup before importing the first sample in
the dataset.

This method is called when the importer’s context manager interface is
entered, `DatasetImporter.__enter__()`.

#### close(\*args)

Performs any necessary actions after the last sample has been
imported.

This method is called when the importer’s context manager interface is
exited, `DatasetImporter.__exit__()`.

* **Parameters:**
  **\*args** – the arguments to `DatasetImporter.__exit__()`