mlflow.tracking

The mlflow.tracking module provides a Python CRUD interface to MLflow experiments and runs. This is a lower level API that directly translates to MLflow REST API calls. For a higher level API for managing an “active run”, use the mlflow module.

class mlflow.tracking.MlflowClient(tracking_uri=None, registry_uri=None)[source]

Bases: object

Client of an MLflow Tracking Server that creates and manages experiments and runs, and of an MLflow Registry Server that creates and manages registered models and model versions. It’s a thin wrapper around TrackingServiceClient and RegistryClient so there is a unified API but we can keep the implementation of the tracking and registry clients independent from each other.

create_experiment(name, artifact_location=None)[source]

Create an experiment.

Parameters
  • name – The experiment name. Must be unique.

  • artifact_location – The location to store run artifacts. If not provided, the server picks an appropriate default.

Returns

Integer ID of the created experiment.

create_model_version(name, source, run_id, tags=None, run_link=None, description=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Create a new model version from given source (artifact URI).

Parameters
  • name – Name for the containing registered model.

  • source – Source path where the MLflow model is stored.

  • run_id – Run ID from MLflow tracking server that generated the model

  • tags – A dictionary of key-value pairs that are converted into mlflow.entities.model_registry.ModelVersionTag objects.

  • run_link – Link to the run from an MLflow tracking server that generated this model.

  • description – Description of the version.

Returns

Single mlflow.entities.model_registry.ModelVersion object created by backend.

create_registered_model(name, tags=None, description=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Create a new registered model in backend store.

Parameters
  • name – Name of the new model. This is expected to be unique in the backend store.

  • tags – A dictionary of key-value pairs that are converted into mlflow.entities.model_registry.RegisteredModelTag objects.

  • description – Description of the model.

Returns

A single object of mlflow.entities.model_registry.RegisteredModel created by backend.

create_run(experiment_id, start_time=None, tags=None)[source]

Create a mlflow.entities.Run object that can be associated with metrics, parameters, artifacts, etc. Unlike mlflow.projects.run(), creates objects but does not run code. Unlike mlflow.start_run(), does not change the “active run” used by mlflow.log_param().

Parameters
  • experiment_id – The ID of then experiment to create a run in.

  • start_time – If not provided, use the current timestamp.

  • tags – A dictionary of key-value pairs that are converted into mlflow.entities.RunTag objects.

Returns

mlflow.entities.Run that was created.

delete_experiment(experiment_id)[source]

Delete an experiment from the backend store.

Parameters

experiment_id – The experiment ID returned from create_experiment.

delete_model_version(name, version)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Delete model version in backend.

Parameters
  • name – Name of the containing registered model.

  • version – Version number of the model version.

delete_model_version_tag(name, version, key)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Delete a tag associated with the model version.

Parameters
  • name – Registered model name.

  • version – Registered model version.

  • key – Tag key.

Returns

None

delete_registered_model(name)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Delete registered model. Backend raises exception if a registered model with given name does not exist.

Parameters

name – Name of the registered model to update.

delete_registered_model_tag(name, key)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Delete a tag associated with the registered model.

Parameters
  • name – Registered model name.

  • key – Registered model tag key.

Returns

None

delete_run(run_id)[source]

Deletes a run with the given ID.

delete_tag(run_id, key)[source]

Delete a tag from a run. This is irreversible.

Parameters
  • run_id – String ID of the run

  • key – Name of the tag

download_artifacts(run_id, path, dst_path=None)[source]

Download an artifact file or directory from a run to a local directory if applicable, and return a local path for it.

Parameters
  • run_id – The run to download artifacts from.

  • path – Relative source path to the desired artifact.

  • dst_path – Absolute path of the local filesystem destination directory to which to download the specified artifacts. This directory must already exist. If unspecified, the artifacts will either be downloaded to a new uniquely-named directory on the local filesystem or will be returned directly in the case of the LocalArtifactRepository.

Returns

Local path of desired artifact.

get_experiment(experiment_id)[source]

Retrieve an experiment by experiment_id from the backend store

Parameters

experiment_id – The experiment ID returned from create_experiment.

Returns

mlflow.entities.Experiment

get_experiment_by_name(name)[source]

Retrieve an experiment by experiment name from the backend store

Parameters

name – The experiment name.

Returns

mlflow.entities.Experiment

get_latest_versions(name, stages=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Latest version models for each requests stage. If no stages provided, returns the latest version for each stage.

Parameters
  • name – Name of the registered model to update.

  • stages – List of desired stages. If input list is None, return latest versions for for ALL_STAGES.

Returns

List of mlflow.entities.model_registry.ModelVersion objects.

get_metric_history(run_id, key)[source]

Return a list of metric objects corresponding to all values logged for a given metric.

Parameters
  • run_id – Unique identifier for run

  • key – Metric name within the run

Returns

A list of mlflow.entities.Metric entities if logged, else empty list

get_model_version(name, version)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Parameters
  • name – Name of the containing registered model.

  • version – Version number of the model version.

Returns

A single mlflow.entities.model_registry.ModelVersion object.

get_model_version_download_uri(name, version)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Get the download location in Model Registry for this model version.

Parameters
  • name – Name of the containing registered model.

  • version – Version number of the model version.

Returns

A single URI location that allows reads for downloading.

get_model_version_stages(name, version)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Returns

A list of valid stages.

get_registered_model(name)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Parameters

name – Name of the registered model to update.

Returns

A single mlflow.entities.model_registry.RegisteredModel object.

get_run(run_id)[source]

Fetch the run from backend store. The resulting Run contains a collection of run metadata – RunInfo, as well as a collection of run parameters, tags, and metrics – RunData. In the case where multiple metrics with the same key are logged for the run, the RunData contains the most recently logged value at the largest step for each metric.

Parameters

run_id – Unique identifier for the run.

Returns

A single mlflow.entities.Run object, if the run exists. Otherwise, raises an exception.

list_artifacts(run_id, path=None)[source]

List the artifacts for a run.

Parameters
  • run_id – The run to list artifacts from.

  • path – The run’s relative artifact path to list from. By default it is set to None or the root artifact path.

Returns

List of mlflow.entities.FileInfo

list_experiments(view_type=None)[source]
Returns

List of mlflow.entities.Experiment

list_registered_models(max_results=100, page_token=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

List of all registered models

Parameters
  • max_results – Maximum number of registered models desired.

  • page_token – Token specifying the next page of results. It should be obtained from a list_registered_models call.

Returns

A PagedList of mlflow.entities.model_registry.RegisteredModel objects that can satisfy the search expressions. The pagination token for the next page can be obtained via the token attribute of the object.

list_run_infos(experiment_id, run_view_type=1, max_results=1000, order_by=None, page_token=None)[source]
Returns

List of mlflow.entities.RunInfo

log_artifact(run_id, local_path, artifact_path=None)[source]

Write a local file or directory to the remote artifact_uri.

Parameters
  • local_path – Path to the file or directory to write.

  • artifact_path – If provided, the directory in artifact_uri to write to.

log_artifacts(run_id, local_dir, artifact_path=None)[source]

Write a directory of files to the remote artifact_uri.

Parameters
  • local_dir – Path to the directory of files to write.

  • artifact_path – If provided, the directory in artifact_uri to write to.

log_batch(run_id, metrics=(), params=(), tags=())[source]

Log multiple metrics, params, and/or tags.

Parameters
  • run_id – String ID of the run

  • metrics – If provided, List of Metric(key, value, timestamp) instances.

  • params – If provided, List of Param(key, value) instances.

  • tags – If provided, List of RunTag(key, value) instances.

Raises an MlflowException if any errors occur. :return: None

log_metric(run_id, key, value, timestamp=None, step=None)[source]

Log a metric against the run ID.

Parameters
  • run_id – The run id to which the metric should be logged.

  • key – Metric name.

  • value – Metric value (float). Note that some special values such as +/- Infinity may be replaced by other values depending on the store. For example, the SQLAlchemy store replaces +/- Inf with max / min float values.

  • timestamp – Time when this metric was calculated. Defaults to the current system time.

  • step – Integer training step (iteration) at which was the metric calculated. Defaults to 0.

log_param(run_id, key, value)[source]

Log a parameter against the run ID. Value is converted to a string.

rename_experiment(experiment_id, new_name)[source]

Update an experiment’s name. The new name must be unique.

Parameters

experiment_id – The experiment ID returned from create_experiment.

rename_registered_model(name, new_name)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Update registered model name.

Parameters
  • name – Name of the registered model to update.

  • new_name – New proposed name for the registered model.

Returns

A single updated mlflow.entities.model_registry.RegisteredModel object.

restore_experiment(experiment_id)[source]

Restore a deleted experiment unless permanently deleted.

Parameters

experiment_id – The experiment ID returned from create_experiment.

restore_run(run_id)[source]

Restores a deleted run with the given ID.

search_model_versions(filter_string)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Search for model versions in backend that satisfy the filter criteria.

Parameters

filter_string – A filter string expression. Currently, it supports a single filter condition either a name of model like name = 'model_name' or run_id = '...'.

Returns

PagedList of mlflow.entities.model_registry.ModelVersion objects.

Example
import mlflow

client = mlflow.tracking.MlflowClient()

# Get all versions of the model filtered by name
model_name = "CordobaWeatherForecastModel"
filter_string = "name='{}'".format(model_name)
results = client.search_model_versions(filter_string)
print("-" * 80)
for res in results:
    print("name={}; run_id={}; version={}".format(res.name, res.run_id, res.version))

# Get the version of the model filtered by run_id
run_id = "e14afa2f47a040728060c1699968fd43"
filter_string = "run_id='{}'".format(run_id)
results = client.search_model_versions(filter_string)
print("-" * 80)
for res in results:
    print("name={}; run_id={}; version={}".format(res.name, res.run_id, res.version))
Output
------------------------------------------------------------------------------------
name=CordobaWeatherForecastModel; run_id=eaef868ee3d14d10b4299c4c81ba8814; version=1
name=CordobaWeatherForecastModel; run_id=e14afa2f47a040728060c1699968fd43; version=2
------------------------------------------------------------------------------------
name=CordobaWeatherForecastModel; run_id=e14afa2f47a040728060c1699968fd43; version=2
search_registered_models(filter_string=None, max_results=100, order_by=None, page_token=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Search for registered models in backend that satisfy the filter criteria.

Parameters
  • filter_string – Filter query string, defaults to searching all registered models. Currently, it supports only a single filter condition as the name of the model, for example, name = 'model_name' or a search expression to match a pattern in the registered model name. For example, name LIKE 'Boston%' (case sensitive) or name ILIKE '%boston%' (case insensitive).

  • max_results – Maximum number of registered models desired.

  • order_by – List of column names with ASC|DESC annotation, to be used for ordering matching search results.

  • page_token – Token specifying the next page of results. It should be obtained from a search_registered_models call.

Returns

A PagedList of mlflow.entities.model_registry.RegisteredModel objects that satisfy the search expressions. The pagination token for the next page can be obtained via the token attribute of the object.

Example
import mlflow

client = mlflow.tracking.MlflowClient()

# Get search results filtered by the registered model name
model_name="CordobaWeatherForecastModel"
filter_string = "name='{}'".format(model_name)
results = client.search_registered_models(filter_string=filter_string)
print("-" * 80)
for res in results:
    for mv in res.latest_versions:
        print("name={}; run_id={}; version={}".format(mv.name, mv.run_id, mv.version))

# Get search results filtered by the registered model name that matches
# prefix pattern
filter_string = "name LIKE 'Boston%'"
results = client.search_registered_models(filter_string=filter_string)
for res in results:
    for mv in res.latest_versions:
    print("name={}; run_id={}; version={}".format(mv.name, mv.run_id, mv.version))

# Get all registered models and order them by ascending order of the names
results = client.search_registered_models(order_by=["name ASC"])
print("-" * 80)
for res in results:
    for mv in res.latest_versions:
        print("name={}; run_id={}; version={}".format(mv.name, mv.run_id, mv.version))
Output
------------------------------------------------------------------------------------
name=CordobaWeatherForecastModel; run_id=eaef868ee3d14d10b4299c4c81ba8814; version=1
name=CordobaWeatherForecastModel; run_id=e14afa2f47a040728060c1699968fd43; version=2
------------------------------------------------------------------------------------
name=BostonWeatherForecastModel; run_id=ddc51b9407a54b2bb795c8d680e63ff6; version=1
name=BostonWeatherForecastModel; run_id=48ac94350fba40639a993e1b3d4c185d; version=2
-----------------------------------------------------------------------------------
name=AzureWeatherForecastModel; run_id=5fcec6c4f1c947fc9295fef3fa21e52d; version=1
name=AzureWeatherForecastModel; run_id=8198cb997692417abcdeb62e99052260; version=3
name=BostonWeatherForecastModel; run_id=ddc51b9407a54b2bb795c8d680e63ff6; version=1
name=BostonWeatherForecastModel; run_id=48ac94350fba40639a993e1b3d4c185d; version=2
name=CordobaWeatherForecastModel; run_id=eaef868ee3d14d10b4299c4c81ba8814; version=1
name=CordobaWeatherForecastModel; run_id=e14afa2f47a040728060c1699968fd43; version=2
search_runs(experiment_ids, filter_string='', run_view_type=1, max_results=1000, order_by=None, page_token=None)[source]

Search experiments that fit the search criteria.

Parameters
  • experiment_ids – List of experiment IDs, or a single int or string id.

  • filter_string – Filter query string, defaults to searching all runs.

  • run_view_type – one of enum values ACTIVE_ONLY, DELETED_ONLY, or ALL runs defined in mlflow.entities.ViewType.

  • max_results – Maximum number of runs desired.

  • order_by – List of columns to order by (e.g., “metrics.rmse”). The order_by column can contain an optional DESC or ASC value. The default is ASC. The default ordering is to sort by start_time DESC, then run_id.

  • page_token – Token specifying the next page of results. It should be obtained from a search_runs call.

Returns

A list of mlflow.entities.Run objects that satisfy the search expressions. If the underlying tracking store supports pagination, the token for the next page may be obtained via the token attribute of the returned object.

set_experiment_tag(experiment_id, key, value)[source]

Set a tag on the experiment with the specified ID. Value is converted to a string.

Parameters
  • experiment_id – String ID of the experiment.

  • key – Name of the tag.

  • value – Tag value (converted to a string).

set_model_version_tag(name, version, key, value)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Set a tag for the model version.

Parameters
  • name – Registered model name.

  • version – Registered model version.

  • key – Tag key to log.

  • value – Tag value to log.

Returns

None

set_registered_model_tag(name, key, value)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Set a tag for the registered model.

Parameters
  • name – Registered model name.

  • key – Tag key to log.

  • value – Tag value log.

Returns

None

set_tag(run_id, key, value)[source]

Set a tag on the run with the specified ID. Value is converted to a string.

Parameters
  • run_id – String ID of the run.

  • key – Name of the tag.

  • value – Tag value (converted to a string)

set_terminated(run_id, status=None, end_time=None)[source]

Set a run’s status to terminated.

Parameters
  • status – A string value of mlflow.entities.RunStatus. Defaults to “FINISHED”.

  • end_time – If not provided, defaults to the current time.

transition_model_version_stage(name, version, stage, archive_existing_versions=False)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Update model version stage.

Parameters
  • name – Registered model name.

  • version – Registered model version.

  • stage – New desired stage for this model version.

  • archive_existing_versions – If this flag is set to True, all existing model versions in the stage will be automically moved to the “archived” stage. Only valid when stage is "staging" or "production" otherwise an error will be raised.

Returns

A single mlflow.entities.model_registry.ModelVersion object.

update_model_version(name, version, description=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Update metadata associated with a model version in backend.

Parameters
  • name – Name of the containing registered model.

  • version – Version number of the model version.

  • description – New description.

Returns

A single mlflow.entities.model_registry.ModelVersion object.

update_registered_model(name, description=None)[source]

Note

Experimental: This method may change or be removed in a future release without warning.

Updates metadata for RegisteredModel entity. Input field description should be non-None. Backend raises exception if a registered model with given name does not exist.

Parameters
  • name – Name of the registered model to update.

  • description – (Optional) New description.

Returns

A single updated mlflow.entities.model_registry.RegisteredModel object.

mlflow.tracking.get_tracking_uri()[source]

Get the current tracking URI. This may not correspond to the tracking URI of the currently active run, since the tracking URI can be updated via set_tracking_uri.

Returns

The tracking URI.

mlflow.tracking.set_tracking_uri(uri)[source]

Set the tracking server URI. This does not affect the currently active run (if one exists), but takes effect for successive runs.

Parameters

uri

  • An empty string, or a local file path, prefixed with file:/. Data is stored locally at the provided file (or ./mlruns if empty).

  • An HTTP URI like https://my-tracking-server:5000.

  • A Databricks workspace, provided as the string “databricks” or, to use a Databricks CLI profile, “databricks://<profileName>”.

mlflow.tracking.is_tracking_uri_set()[source]

Returns True if the tracking URI has been set, False otherwise.

mlflow.tracking.get_registry_uri()[source]

Get the current registry URI. If none has been specified, defaults to the tracking URI.

Returns

The registry URI.

mlflow.tracking.set_registry_uri(uri)[source]

Set the registry server URI. This method is especially useful if you have a registry server that’s different from the tracking server.

Parameters

uri

  • An empty string, or a local file path, prefixed with file:/. Data is stored locally at the provided file (or ./mlruns if empty).

  • An HTTP URI like https://my-tracking-server:5000.

  • A Databricks workspace, provided as the string “databricks” or, to use a Databricks CLI profile, “databricks://<profileName>”.