# fiftyone.migrations.runner FiftyOne migrations runner. Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)

**Functions:** | [`Version`](#fiftyone.migrations.runner.Version)(version) | A `packaging.version.Version` proxy that excludes things like RC version info. | |------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| | [`get_database_revision`](#fiftyone.migrations.runner.get_database_revision)() | Gets the current revision of the database. | | [`get_dataset_revision`](#fiftyone.migrations.runner.get_dataset_revision)(name) | Gets the current revision of the given dataset. | | [`get_datasets_revisions`](#fiftyone.migrations.runner.get_datasets_revisions)() | Gets the current revision of all datasets. | | [`migrate_all`](#fiftyone.migrations.runner.migrate_all)([destination, error_level, verbose]) | Migrates the database and all datasets to the specified destination revision. | | [`migrate_database_if_necessary`](#fiftyone.migrations.runner.migrate_database_if_necessary)([destination, ...]) | Migrates the database to the specified revision, if necessary. | | [`needs_migration`](#fiftyone.migrations.runner.needs_migration)([name, head, destination]) | Determines whether a dataset requires a migration in order to be used in the specified destination revision. | | [`migrate_dataset_if_necessary`](#fiftyone.migrations.runner.migrate_dataset_if_necessary)(name[, ...]) | Migrates the dataset from its current revision to the specified destination revision. | **Classes:** | [`MigrationRunner`](#fiftyone.migrations.runner.MigrationRunner)(head, destination[, ...]) | Class for running FiftyOne migrations. | |----------------------------------------------------------------------------------------------|------------------------------------------| ### fiftyone.migrations.runner.Version(version) A `packaging.version.Version` proxy that excludes things like RC version info. ### fiftyone.migrations.runner.get_database_revision() Gets the current revision of the database. * **Returns:** the database revision string ### fiftyone.migrations.runner.get_dataset_revision(name) Gets the current revision of the given dataset. * **Parameters:** **name** – the name of the dataset * **Returns:** the dataset revision string ### fiftyone.migrations.runner.get_datasets_revisions() Gets the current revision of all datasets. * **Returns:** a dictionary mapping dataset names to their revision strings ### fiftyone.migrations.runner.migrate_all(destination=None, error_level=0, verbose=False) Migrates the database and all datasets to the specified destination revision. If `fiftyone.config.database_admin` is `False` and no `destination` is provided, the database and each dataset will only be migrated if their current versions are not compatible with the client’s version. * **Parameters:** * **destination** (*None*) – the destination revision. By default, the `fiftyone` client version is used * **error_level** (*0*) – the error level to use if an individual dataset cannot be migrated. Valid values are: - 0: raise error if a dataset cannot be migrated - 1: log warning if a dataset cannot be migrated - 2: ignore datasets that cannot be migrated * **verbose** (*False*) – whether to log incremental migrations that are run ### fiftyone.migrations.runner.migrate_database_if_necessary(destination=None, verbose=False, config=None) Migrates the database to the specified revision, if necessary. If `fiftyone.config.database_admin` is `False` and no `destination` is provided, the database will only be migrated if its current version is not compatible with the client’s version. * **Parameters:** * **destination** (*None*) – the destination revision. By default, the `fiftyone` client version is used * **verbose** (*False*) – whether to log incremental migrations that are run * **config** (*None*) – an optional `DatabaseConfigDocument`. By default, DB config is pulled from the database. ### fiftyone.migrations.runner.needs_migration(name=None, head=None, destination=None) Determines whether a dataset requires a migration in order to be used in the specified destination revision. To use this method, specify either the `name` of an existing dataset or provide the `head` revision of the dataset. If `fiftyone.config.database_admin` is `False` and no `destination` is provided, a dataset will be deemed to require no migration if its current version if compatible with the client’s version. * **Parameters:** * **name** (*None*) – the name of the dataset * **head** (*None*) – the current revision of the dataset * **destination** (*None*) – the destination revision. By default, the current database version is used * **Returns:** True/False ### fiftyone.migrations.runner.migrate_dataset_if_necessary(name, destination=None, error_level=0, verbose=False) Migrates the dataset from its current revision to the specified destination revision. If `fiftyone.config.database_admin` is `False` and no `destination` is provided, the dataset will only be migrated if its current version is not compatible with the client’s version. * **Parameters:** * **name** – the name of the dataset * **destination** (*None*) – the destination revision. By default, the current database version is used * **error_level** (*0*) – the error level to use. Valid values are: - 0: raise error if the dataset cannot be migrated - 1: log warning if the dataset cannot be migrated - 2: ignore datasets that cannot be migrated * **verbose** (*False*) – whether to log incremental migrations that are run ### *class* fiftyone.migrations.runner.MigrationRunner(head, destination, \_revisions=None, \_admin_revisions=None) Bases: `object` Class for running FiftyOne migrations. * **Parameters:** * **head** – the current revision * **destination** – the destination revision **Attributes:** | [`head`](#fiftyone.migrations.runner.MigrationRunner.head) | The head revision. | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | [`destination`](#fiftyone.migrations.runner.MigrationRunner.destination) | The destination revision. | | [`direction`](#fiftyone.migrations.runner.MigrationRunner.direction) | The direction of the migration runner; one of `("up", "down").` | | [`has_revisions`](#fiftyone.migrations.runner.MigrationRunner.has_revisions) | Whether there are any revisions to run. | | [`has_admin_revisions`](#fiftyone.migrations.runner.MigrationRunner.has_admin_revisions) | Whether there are any admin revisions to run. | | [`revisions`](#fiftyone.migrations.runner.MigrationRunner.revisions) | The list of revisions that will be run by [`run()`](#fiftyone.migrations.runner.MigrationRunner.run). | | [`admin_revisions`](#fiftyone.migrations.runner.MigrationRunner.admin_revisions) | The list of admin revisions that will be run by [`run_admin()`](#fiftyone.migrations.runner.MigrationRunner.run_admin). | **Methods:** | [`run`](#fiftyone.migrations.runner.MigrationRunner.run)(dataset_name[, verbose]) | Runs any required migrations on the specified dataset. | |-------------------------------------------------------------------------------------|----------------------------------------------------------| | [`run_admin`](#fiftyone.migrations.runner.MigrationRunner.run_admin)([verbose]) | Runs any required admin revisions. | #### *property* head The head revision. #### *property* destination The destination revision. #### *property* direction The direction of the migration runner; one of `("up", "down").` #### *property* has_revisions Whether there are any revisions to run. #### *property* has_admin_revisions Whether there are any admin revisions to run. #### *property* revisions The list of revisions that will be run by [`run()`](#fiftyone.migrations.runner.MigrationRunner.run). #### *property* admin_revisions The list of admin revisions that will be run by [`run_admin()`](#fiftyone.migrations.runner.MigrationRunner.run_admin). #### run(dataset_name, verbose=False) Runs any required migrations on the specified dataset. * **Parameters:** * **dataset_name** – the name of the dataset to migrate * **verbose** (*False*) – whether to log incremental migrations that are run #### run_admin(verbose=False) Runs any required admin revisions. * **Parameters:** **verbose** (*False*) – whether to log incremental migrations that are run