docs/docs/self-hosting/migrate-from-file-store.mdx
If you have existing data in a file-based backend (./mlruns), you can migrate it to a database using the built-in migration command.
You must have MLflow 3.10 or later installed. Run the following command to upgrade if needed:
pip install 'mlflow>=3.10'
If you're running a tracking server, stop it before migrating. Then run:
mlflow migrate-filestore --source /path/to/mlruns --target sqlite:///path/to/mlflow.db
:::note The migration tool only supports SQLite as the target database. See Important Notes for details. :::
This reads all data from the specified directory and writes it to the specified SQLite database. The migration is atomic for the migrated data: if any error occurs, all inserted rows are rolled back and no migrated data is committed, so you can safely re-run the command after fixing the issue.
Once complete, start the server with the new database. If you haven't explicitly set a --backend-store-uri, the tracking server will use ./mlruns if existing file-based experiment data is found there, and fall back to sqlite:///mlflow.db otherwise. To avoid relying on these defaults, explicitly point the server to the new database:
mlflow server --backend-store-uri sqlite:///path/to/mlflow.db
Open the MLflow UI and confirm your experiments, runs, and models are present.
The migration tool transfers all metadata stored in the file-based backend:
| Category | Entities |
|---|---|
| Experiments | Experiments, experiment tags |
| Runs | Runs, params, metrics, latest metrics, tags |
| Datasets | Datasets, inputs, input tags |
| Run I/O | Model inputs (run → model), model outputs (run → model) |
| Traces | Trace info, trace tags, trace request metadata |
| Assessments | Assessments (feedback, expectations) |
| Logged Models | Logged models, tags |
| Model Registry | Registered models, model versions, tags, aliases |
| Prompts | Prompts (stored as registered models and model versions) |
The migration tool preserves your data exactly as it was in the FileStore. No timestamps are altered.
creation_time, start_time, end_time, last_update_time) retain their original millisecond precision..trash directory are migrated with their deleted lifecycle stage preserved.mlflow-export-importmlflow-export-import is a separate tool for copying MLflow objects (runs, experiments, registered models, etc.) from one tracking server to another. It is useful for moving between environments but does not preserve original IDs or timestamps.
mlflow migrate-filestore | mlflow-export-import | |
|---|---|---|
| Use case | Migrate FileStore to a database | Copy objects between MLflow servers |
| Preserves IDs and timestamps | Yes | No (regenerated on import) |
| Requires a running server | No | Yes (both source and target) |
| Target | SQLite Only | Any MLflow server |
:::warning
The filesystem backend is in maintenance mode and will not receive further updates. The recommended path is to migrate to a database backend using mlflow migrate-filestore, which preserves your existing data losslessly.
:::
This escape hatch exists for the rare case where migration is genuinely not an option (for example, browsing read-only mlruns data synced from an HPC cluster that cannot run a database, or sharing a directory snapshot across machines via rsync). If your workflow does not have such a constraint, please use the migration tool above instead.
To opt out of the error and continue using the filesystem backend, set the MLFLOW_ALLOW_FILE_STORE environment variable before starting the MLflow server or running any client code:
export MLFLOW_ALLOW_FILE_STORE=true
mlflow server --backend-store-uri ./mlruns
If you run into issues or have feedback (e.g., support for PostgreSQL/MySQL), please comment on GitHub issue #18534.