---
title: README
author: Jan-Michael Rye
---

[insert: badges gitlab]: #

[![Hatch](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![Latest Release](https://gitlab.inria.fr/jrye/mlflow-extra/-/badges/release.svg)](https://gitlab.inria.fr/jrye/mlflow-extra/-/tags) [![License](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/MIT.html) [![Pipeline Status](https://gitlab.inria.fr/jrye/mlflow-extra/badges/main/pipeline.svg)](https://gitlab.inria.fr/jrye/mlflow-extra/-/commits/main) [![PyPI](https://img.shields.io/badge/PyPI-mlflow--extra-006dad.svg)](https://pypi.org/project/mlflow-extra/) [![PyPI Downloads](https://static.pepy.tech/badge/mlflow-extra)](https://pepy.tech/projects/mlflow-extra) [![Pylint](https://gitlab.inria.fr/jrye/mlflow-extra/-/jobs/artifacts/main/raw/pylint/pylint.svg?job=pylint)](https://gitlab.inria.fr/jrye/mlflow-extra/-/jobs/artifacts/main/raw/pylint/pylint.txt?job=pylint)

[/insert: badges gitlab]: #


# Synopsis

Provides several command-line utilities for working with MLflow, such as merging experiments from one backend to another and fixing artifact paths after moving a local `mlruns` directory. Versions prior to 2026 worked directly on `meta.yaml` file in local `mlruns` directories. Starting with version 2026.1, the commands have been updated to use [mlflow.client.MlflowClient](https://mlflow.org/docs/latest/api_reference/python_api/mlflow.client.html) which uses the [MLflow REST API](https://mlflow.org/docs/latest/api_reference/rest-api.html) as the previous File Store has been deprecated. For migration details, see [Migrate from File Store to Database](https://mlflow.org/docs/latest/self-hosting/migrate-from-file-store/).

## Links

[insert: links 2]: #

### GitLab

* [Homepage](https://gitlab.inria.fr/jrye/mlflow-extra)
* [Source](https://gitlab.inria.fr/jrye/mlflow-extra.git)
* [Issues](https://gitlab.inria.fr/jrye/mlflow-extra/issues)
* [Documentation](https://jrye.gitlabpages.inria.fr/mlflow-extra)
* [GitLab package registry](https://gitlab.inria.fr/jrye/mlflow-extra/-/packages)

### Other Repositories

* [Python Package Index (PyPI)](https://pypi.org/project/mlflow-extra/)

[/insert: links 2]: #

# Installation

Install the [MLflow Extra package](https://pypi.org/project/mlflow-extra) from the [Python Package Index](https://pypi.org/) using any standard Python package manager, e.g.

~~~sh
# Uncomment the following 2 lines to create and activate a virtual environment.
# python -m venv venv
# source venv/bin/activate
pip3 install --upgrade mlflow-extra
~~~

It can also be installed from source with any standard Python package manager that supports [pyproject.toml](https://peps.python.org/pep-0621/) files. For example, to install it with pip, either locally or in a virtual environment, run the following commands:

~~~sh
git clone https://gitlab.inria.fr/jrye/mlflow-extra
cd mlflow-extra
# Uncomment the following 2 lines to create and activate a virtual environment.
# python -m venv venv
# source venv/bin/activate
pip install --upgrade .
~~~

# Commands

These commands provide complimentary functionality for the [mlflow command-line interface](https://mlflow.org/docs/latest/cli.html).

## mlflow-filter_runs

A command-line tool to filter runs in an experiment using either metric threshold values or the total number of runs to keep.

[insert: command_output mlflow-filter_runs -h]: #

~~~
usage: mlflow-filter_runs [-h] [-a] [-c] [-l] [-m METRICS [METRICS ...]]
                          [-n NUMBER] [-t THRESHOLDS [THRESHOLDS ...]]
                          experiment_id [experiment_id ...]

Delete runs from experiment based on thresholds.

positional arguments:
  experiment_id         The MLflow experiment ID (see mlflow experiments
                        list).

options:
  -h, --help            show this help message and exit
  -a, --ascending       Keep the first n runs in ascending order instead of
                        descending.
  -c, --confirm         Confirm the deletion. Without this only a dryrun is
                        performed.
  -l, --list            List metrics and their statistics.
  -m, --metrics METRICS [METRICS ...]
                        The metrics by which to filter runs.
  -n, --number NUMBER   The number of runs to keep.
  -t, --thresholds THRESHOLDS [THRESHOLDS ...]
                        The threshold values for the selected metrics. In
                        descending order the threshold values are a lower
                        limit. In ascending order they are an upper limit.

~~~

[/insert: command_output mlflow-filter_runs -h]: #


## mlflow-fix_artifacts

A command-line tool for fixing artifact URIs in runs when the artifact directories have been moved. Previously this worked on local data in the deprecated File Store backend (i.e. the `mlruns` directory and the `meta.yaml` files therein). The current version only works under the following conditions:

* The MLflow backend is a local SQLite database (e.g. `mlflow.db`).
* The artifacts are located in a directory following the `mlruns` structure, i.e. in subdirectories of the format `<experiment ID>/<run ID>/artifacts`.

[insert: command_output mlflow-fix_artifacts -h]: #

[/ insert: command_output mlflow-fix_artifacts -h]: #


## mlflow-merge

A command-line tool to merge data from one backend to another. Currently this only supports the following:

* experiments
* runs (parameters, metrics, artifacts)
* models (versions and aliases are not yet copied from the source)

Support for models and datasets will be added later.

[insert: command_output mlflow-merge -h]: #

~~~
usage: mlflow-merge [-h] [--tua TUA] [--rua RUA] [--wua WUA] [--tub TUB]
                    [--rub RUB] [--wub WUB]

Copy experiments and runs from one backend to another. This is a work in
progress and should be used with caution.

options:
  -h, --help  show this help message and exit
  --tua TUA   Tracking URI for the source backend.
  --rua RUA   Registry URI for the source backend.
  --wua WUA   Workspace store URI for the source backend.
  --tub TUB   Tracking URI for the destination backend.
  --rub RUB   Registry URI for the destination backend.
  --wub WUB   Workspace store URI for the destination backend.

~~~

[/insert: command_output mlflow-merge -h]: #

### Alternatives

* [mlflow-export-import](https://github.com/mlflow/mlflow-export-import) - I was not able to test this due to a conflicting dependency error when I tried to install it in a clean virtual environment, but it is often recommended in MLflow discussions that I have found online.

# Deprecated Commands

The following commands have been removed after the deprecation of the File Store backend.

* mlflow-fix_experiment_ids


# Python Module

See the [online documentation](https://jrye.gitlabpages.inria.fr/mlflow-extra/) for details.

# Utility Scripts

Some utility scripts are provided for convenience.

## install.sh

[install.sh](https://gitlab.inria.fr/jrye/mlflow-extra/-/blob/main/scripts/install.sh) will optionally set up a virtual environment and then install MLflow Extra from source with pip. See `install.sh -h` for details.

## install_and_run.sh

[install_and_run.sh](https://gitlab.inria.fr/jrye/mlflow-extra/-/blob/main/scripts/install_and_run.sh) will run any of the commands in the MLflow Extra package after ensuring that they are available by installing the package from source if necessary. It is useful for quickly fixing artifacts paths when transferring mlruns directories. See `install_and_run.sh -h` for details.
