Command-Line Interface

The MLflow command-line interface (CLI) provides a simple interface to various functionality in MLflow. You can use the CLI to run projects, start the tracking UI, create and list experiments, download run artifacts, serve MLflow Python Function and scikit-learn models, and serve models on Microsoft Azure Machine Learning and Amazon SageMaker.

Each individual command has a detailed help screen accessible via mlflow command_name --help.

mlflow

mlflow [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

artifacts

Upload, list, and download artifacts from an MLflow artifact repository.

To manage artifacts for a run associated with a tracking server, set the MLFLOW_TRACKING_URI environment variable to the URL of the desired server.

mlflow artifacts [OPTIONS] COMMAND [ARGS]...

download

Download an artifact file or directory to a local directory. The output is the name of the file or directory on the local disk.

Either --run-id or --artifact-uri must be provided.

mlflow artifacts download [OPTIONS]

Options

-r, --run-id <run_id>

Run ID from which to download

-a, --artifact-path <artifact_path>

For use with Run ID: if specified, a path relative to the run’s root directory to download

-u, --artifact-uri <artifact_uri>

URI pointing to the artifact file or artifacts directory; use as an alternative to specifying –run_id and –artifact-path

list

Return all the artifacts directly under run’s root artifact directory, or a sub-directory. The output is a JSON-formatted list.

mlflow artifacts list [OPTIONS]

Options

-r, --run-id <run_id>

Run ID to be listed [required]

-a, --artifact-path <artifact_path>

If specified, a path relative to the run’s root directory to list.

log-artifact

Log a local file as an artifact of a run, optionally within a run-specific artifact path. Run artifacts can be organized into directories, so you can place the artifact in a directory this way.

mlflow artifacts log-artifact [OPTIONS]

Options

-l, --local-file <local_file>

Local path to artifact to log [required]

-r, --run-id <run_id>

Run ID into which we should log the artifact. [required]

-a, --artifact-path <artifact_path>

If specified, we will log the artifact into this subdirectory of the run’s artifact directory.

log-artifacts

Log the files within a local directory as an artifact of a run, optionally within a run-specific artifact path. Run artifacts can be organized into directories, so you can place the artifact in a directory this way.

mlflow artifacts log-artifacts [OPTIONS]

Options

-l, --local-dir <local_dir>

Directory of local artifacts to log [required]

-r, --run-id <run_id>

Run ID into which we should log the artifact. [required]

-a, --artifact-path <artifact_path>

If specified, we will log the artifact into this subdirectory of the run’s artifact directory.

azureml

Serve models on Azure ML. These commands require that MLflow be installed with Python 3.

To serve a model associated with a run on a tracking server, set the MLFLOW_TRACKING_URI environment variable to the URL of the desired server.

mlflow azureml [OPTIONS] COMMAND [ARGS]...

build-image

Note

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

Register an MLflow model with Azure ML and build an Azure ML ContainerImage for deployment. The resulting image can be deployed as a web service to Azure Container Instances (ACI) or Azure Kubernetes Service (AKS).

The resulting Azure ML ContainerImage will contain a webserver that processes model queries. For information about the input data formats accepted by this webserver, see the following documentation: https://www.mlflow.org/docs/latest/models.html#azureml-deployment.

mlflow azureml build-image [OPTIONS]

Options

-m, --model-uri <model_uri>

URI to the model. A local path, a ‘runs:/’ URI, or a remote storage URI (e.g., an ‘s3://’ URI). For more information about supported remote URIs for model artifacts, see https://mlflow.org/docs/latest/tracking.html#artifact-stores [required]

-w, --workspace-name <workspace_name>

The name of the Azure Workspace in which to build the image. [required]

-s, --subscription-id <subscription_id>

The subscription id associated with the Azure Workspace in which to build the image

-i, --image-name <image_name>

The name to assign the Azure Container Image that is created. If unspecified, a unique image name will be generated.

-n, --model-name <model_name>

The name to assign the Azure Model that is created. If unspecified, a unique image name will be generated.

--mlflow-home <mlflow_home>

Path to local clone of MLflow project. Use for development only.

-d, --description <description>

A string description to associate with the Azure Container Image and the Azure Model that are created.

-t, --tags <tags>

A collection of tags, represented as a JSON-formatted dictionary of string key-value pairs, to associate with the Azure Container Image and the Azure Model that are created. These tags are added to a set of default tags that include the model path, the model run id (if specified), and more.

db

Commands for managing an MLflow tracking database.

mlflow db [OPTIONS] COMMAND [ARGS]...

upgrade

Upgrade the schema of an MLflow tracking database to the latest supported version.

IMPORTANT: Schema migrations can be slow and are not guaranteed to be transactional - always take a backup of your database before running migrations. The migrations README, which is located at https://github.com/mlflow/mlflow/blob/master/mlflow/store/db_migrations/README, describes large migrations and includes information about how to estimate their performance and recover from failures.

mlflow db upgrade [OPTIONS] URL

Arguments

URL

Required argument

experiments

Manage experiments. To manage experiments associated with a tracking server, set the MLFLOW_TRACKING_URI environment variable to the URL of the desired server.

mlflow experiments [OPTIONS] COMMAND [ARGS]...

create

Create an experiment.

All artifacts generated by runs related to this experiment will be stored under artifact location, organized under specific run_id sub-directories.

Implementation of experiment and metadata store is dependent on backend storage. FileStore creates a folder for each experiment ID and stores metadata in meta.yaml. Runs are stored as subfolders.

mlflow experiments create [OPTIONS]

Options

-n, --experiment-name <experiment_name>

[required]

-l, --artifact-location <artifact_location>

Base location for runs to store artifact results. Artifacts will be stored at $artifact_location/$run_id/artifacts. See https://mlflow.org/docs/latest/tracking.html#where-runs-are-recorded for more info on the properties of artifact location. If no location is provided, the tracking server will pick a default.

csv

Generate CSV with all runs for an experiment

mlflow experiments csv [OPTIONS]

Options

-x, --experiment-id <experiment_id>

[required]

-o, --filename <filename>

delete

Mark an active experiment for deletion. This also applies to experiment’s metadata, runs and associated data, and artifacts if they are store in default location. Use list command to view artifact location. Command will throw an error if experiment is not found or already marked for deletion.

Experiments marked for deletion can be restored using restore command, unless they are permanently deleted.

Specific implementation of deletion is dependent on backend stores. FileStore moves experiments marked for deletion under a .trash folder under the main folder used to instantiate FileStore. Experiments marked for deletion can be permanently deleted by clearing the .trash folder. It is recommended to use a cron job or an alternate workflow mechanism to clear .trash folder.

mlflow experiments delete [OPTIONS]

Options

-x, --experiment-id <experiment_id>

[required]

list

List all experiments in the configured tracking server.

mlflow experiments list [OPTIONS]

Options

-v, --view <view>

Select view type for list experiments. Valid view types are ‘active_only’ (default), ‘deleted_only’, and ‘all’.

rename

Renames an active experiment. Returns an error if the experiment is inactive.

mlflow experiments rename [OPTIONS]

Options

-x, --experiment-id <experiment_id>

[required]

--new-name <new_name>

[required]

restore

Restore a deleted experiment. This also applies to experiment’s metadata, runs and associated data. The command throws an error if the experiment is already active, cannot be found, or permanently deleted.

mlflow experiments restore [OPTIONS]

Options

-x, --experiment-id <experiment_id>

[required]

models

Deploy MLflow models locally.

To deploy a model associated with a run on a tracking server, set the MLFLOW_TRACKING_URI environment variable to the URL of the desired server.

mlflow models [OPTIONS] COMMAND [ARGS]...

build-docker

EXPERIMENTAL: Builds a Docker image whose default entrypoint serves the specified MLflow model at port 8080 within the container, using the ‘python_function’ flavor.

For example, the following command builds a docker image named ‘my-image-name’ that serves the model from run ‘some-run-uuid’ at run-relative artifact path ‘my-model’:

mlflow models build-docker -m "runs:/some-run-uuid/my-model" -n "my-image-name"

We can then serve the model, exposing it at port 5001 on the host via:

docker run -p 5001:8080 "my-image-name"

NB: by default, the container will start nginx and gunicorn processes. If you don’t need the nginx process to be started (for instance if you deploy your container to Google Cloud Run), you can disable it via the DISABLE_NGINX environment variable:

See https://www.mlflow.org/docs/latest/python_api/mlflow.pyfunc.html for more information on the ‘python_function’ flavor.

This command is experimental (may be changed or removed in a future release without warning) and does not guarantee that the arguments nor format of the Docker container will remain the same.

mlflow models build-docker [OPTIONS]

Options

-m, --model-uri <model_uri>

URI to the model. A local path, a ‘runs:/’ URI, or a remote storage URI (e.g., an ‘s3://’ URI). For more information about supported remote URIs for model artifacts, see https://mlflow.org/docs/latest/tracking.html#artifact-stores [required]

-n, --name <name>

Name to use for built image

--install-mlflow

If specified and there is a conda environment to be activated mlflow will be installed into the environment after it has been activated. The version of installed mlflow will be the same asthe one used to invoke this command.

predict

Generate predictions in json format using a saved MLflow model. For information about the input data formats accepted by this function, see the following documentation: https://www.mlflow.org/docs/latest/models.html#built-in-deployment-tools.

mlflow models predict [OPTIONS]

Options

-m, --model-uri <model_uri>

URI to the model. A local path, a ‘runs:/’ URI, or a remote storage URI (e.g., an ‘s3://’ URI). For more information about supported remote URIs for model artifacts, see https://mlflow.org/docs/latest/tracking.html#artifact-stores [required]

-i, --input-path <input_path>

CSV containing pandas DataFrame to predict against.

-o, --output-path <output_path>

File to output results to as json file. If not provided, output to stdout.

-t, --content-type <content_type>

Content type of the input file. Can be one of {‘json’, ‘csv’}.

-j, --json-format <json_format>

Only applies if the content type is ‘json’. Specify how the data is encoded. Can be one of {‘split’, ‘records’} mirroring the behavior of Pandas orient attribute. The default is ‘split’ which expects dict like data: {‘index’ -> [index], ‘columns’ -> [columns], ‘data’ -> [values]}, where index is optional. For more information see https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_json.html

--no-conda

If specified, will assume that MLmodel/MLproject is running within a Conda environment with the necessary dependencies for the current project instead of attempting to create a new conda environment.

--install-mlflow

If specified and there is a conda environment to be activated mlflow will be installed into the environment after it has been activated. The version of installed mlflow will be the same asthe one used to invoke this command.

serve

Serve a model saved with MLflow by launching a webserver on the specified host and port. For information about the input data formats accepted by the webserver, see the following documentation: https://www.mlflow.org/docs/latest/models.html#built-in-deployment-tools.

You can make requests to POST /invocations in pandas split- or record-oriented formats.

Example:

$ mlflow models serve -m runs:/my-run-id/model-path &

$ curl http://127.0.0.1:5000/invocations -H 'Content-Type: application/json' -d '{
    "columns": ["a", "b", "c"],
    "data": [[1, 2, 3], [4, 5, 6]]
}'
mlflow models serve [OPTIONS]

Options

-m, --model-uri <model_uri>

URI to the model. A local path, a ‘runs:/’ URI, or a remote storage URI (e.g., an ‘s3://’ URI). For more information about supported remote URIs for model artifacts, see https://mlflow.org/docs/latest/tracking.html#artifact-stores [required]

-p, --port <port>

The port to listen on (default: 5000).

-h, --host <host>

The network address to listen on (default: 127.0.0.1). Use 0.0.0.0 to bind to all addresses if you want to access the tracking server from other machines.

-w, --workers <workers>

Number of gunicorn worker processes to handle requests (default: 4).

--no-conda

If specified, will assume that MLmodel/MLproject is running within a Conda environment with the necessary dependencies for the current project instead of attempting to create a new conda environment.

--install-mlflow

If specified and there is a conda environment to be activated mlflow will be installed into the environment after it has been activated. The version of installed mlflow will be the same asthe one used to invoke this command.

run

Run an MLflow project from the given URI.

For local runs, the run will block until it completes. Otherwise, the project will run asynchronously.

If running locally (the default), the URI can be either a Git repository URI or a local path. If running on Databricks, the URI must be a Git repository.

By default, Git projects run in a new working directory with the given parameters, while local projects run from the project’s root directory.

mlflow run [OPTIONS] URI

Options

-e, --entry-point <entry_point>

Entry point within project. [default: main]. If the entry point is not found, attempts to run the project file with the specified name as a script, using ‘python’ to run .py files and the default shell (specified by environment variable $SHELL) to run .sh files

-v, --version <version>

Version of the project to run, as a Git commit reference for Git projects.

-P, --param-list <param_list>

A parameter for the run, of the form -P name=value. Provided parameters that are not in the list of parameters for an entry point will be passed to the corresponding entry point as command-line arguments in the form –name value

--experiment-name <experiment_name>

Name of the experiment under which to launch the run. If not specified, ‘experiment-id’ option will be used to launch run.

--experiment-id <experiment_id>

ID of the experiment under which to launch the run.

-b, --backend <backend>

Execution backend to use for run. Supported values: ‘local’, ‘databricks’, kubernetes (experimental). Defaults to ‘local’. If running against Databricks, will run against a Databricks workspace determined as follows: if a Databricks tracking URI of the form ‘databricks://profile’ has been set (e.g. by setting the MLFLOW_TRACKING_URI environment variable), will run against the workspace specified by <profile>. Otherwise, runs against the workspace specified by the default Databricks CLI profile. See https://github.com/databricks/databricks-cli for more info on configuring a Databricks CLI profile.

-c, --backend-config <backend_config>

Path to JSON file (must end in ‘.json’) or JSON string which will be passed as config to the backend. The exact content which should be provided is different for each execution backend and is documented at https://www.mlflow.org/docs/latest/projects.html.

--no-conda

If specified, will assume that MLmodel/MLproject is running within a Conda environment with the necessary dependencies for the current project instead of attempting to create a new conda environment.

--storage-dir <storage_dir>

Only valid when backend is local.MLflow downloads artifacts from distributed URIs passed to parameters of type ‘path’ to subdirectories of storage_dir.

--run-id <run_id>

If specified, the given run ID will be used instead of creating a new run. Note: this argument is used internally by the MLflow project APIs and should not be specified.

Arguments

URI

Required argument

Environment variables

MLFLOW_EXPERIMENT_NAME
Provide a default for --experiment-name
MLFLOW_EXPERIMENT_ID
Provide a default for --experiment-id
MLFLOW_TMP_DIR
Provide a default for --storage-dir

runs

Manage runs. To manage runs of experiments associated with a tracking server, set the MLFLOW_TRACKING_URI environment variable to the URL of the desired server.

mlflow runs [OPTIONS] COMMAND [ARGS]...

delete

Mark a run for deletion. Return an error if the run does not exist or is already marked. You can restore a marked run with restore_run, or permanently delete a run in the backend store.

mlflow runs delete [OPTIONS]

Options

--run-id <run_id>

[required]

describe

All of run details will print to the stdout as JSON format.

mlflow runs describe [OPTIONS]

Options

--run-id <run_id>

[required]

list

List all runs of the specified experiment in the configured tracking server.

mlflow runs list [OPTIONS]

Options

--experiment-id <experiment_id>

Specify the experiment ID for list of runs. [required]

-v, --view <view>

Select view type for list experiments. Valid view types are ‘active_only’ (default), ‘deleted_only’, and ‘all’.

Environment variables

MLFLOW_EXPERIMENT_ID
Provide a default for --experiment-id

restore

Restore a deleted run. Returns an error if the run is active or has been permanently deleted.

mlflow runs restore [OPTIONS]

Options

--run-id <run_id>

[required]

sagemaker

Serve models on SageMaker.

To serve a model associated with a run on a tracking server, set the MLFLOW_TRACKING_URI environment variable to the URL of the desired server.

mlflow sagemaker [OPTIONS] COMMAND [ARGS]...

build-and-push-container

Build new MLflow Sagemaker image, assign it a name, and push to ECR.

This function builds an MLflow Docker image. The image is built locally and it requires Docker to run. The image is pushed to ECR under current active AWS account and to current active AWS region.

mlflow sagemaker build-and-push-container [OPTIONS]

Options

--build, --no-build

Build the container if set.

--push, --no-push

Push the container to AWS ECR if set.

-c, --container <container>

image name

--mlflow-home <mlflow_home>

Path to local clone of MLflow project. Use for development only.

delete

Delete the specified application. Unless --archive is specified, all SageMaker resources associated with the application are deleted as well.

By default, unless the --async flag is specified, this command will block until either the deletion process completes (definitively succeeds or fails) or the specified timeout elapses.

mlflow sagemaker delete [OPTIONS]

Options

-a, --app-name <app_name>

Application name [required]

-r, --region-name <region_name>

Name of the AWS region in which to deploy the application.

-ar, --archive

If specified, resources associated with the application are preserved. These resources may include unused SageMaker models and endpoint configurations that were previously associated with the application endpoint. Otherwise, if –archive is unspecified, these resources are deleted. –archive must be specified when deleting asynchronously with –async.

--async

If specified, this command will return immediately after starting the deletion process. It will not wait for the deletion process to complete. The caller is responsible for monitoring the deletion process via native SageMaker APIs or the AWS console.

--timeout <timeout>

If the command is executed synchronously, the deployment process will return after the specified number of seconds if no definitive result (success or failure) is achieved. Once the function returns, the caller is responsible for monitoring the health and status of the pending deployment via native SageMaker APIs or the AWS console. If the command is executed asynchronously using the –async flag, this value is ignored.

deploy

Deploy model on Sagemaker as a REST API endpoint. Current active AWS account needs to have correct permissions setup.

By default, unless the --async flag is specified, this command will block until either the deployment process completes (definitively succeeds or fails) or the specified timeout elapses.

For more information about the input data formats accepted by the deployed REST API endpoint, see the following documentation: https://www.mlflow.org/docs/latest/models.html#sagemaker-deployment.

mlflow sagemaker deploy [OPTIONS]

Options

-a, --app-name <app_name>

Application name [required]

-m, --model-uri <model_uri>

URI to the model. A local path, a ‘runs:/’ URI, or a remote storage URI (e.g., an ‘s3://’ URI). For more information about supported remote URIs for model artifacts, see https://mlflow.org/docs/latest/tracking.html#artifact-stores [required]

-e, --execution-role-arn <execution_role_arn>

SageMaker execution role

-b, --bucket <bucket>

S3 bucket to store model artifacts

-i, --image-url <image_url>

ECR URL for the Docker image

--region-name <region_name>

Name of the AWS region in which to deploy the application

--mode <mode>

The mode in which to deploy the application. Must be one of the following: create, add, replace

-ar, --archive

If specified, any SageMaker resources that become inactive (i.e as the result of an update in replace mode) are preserved. These resources may include unused SageMaker models and endpoint configurations that were associated with a prior version of the application endpoint. Otherwise, if –archive is unspecified, these resources are deleted. –archive must be specified when deploying asynchronously with –async.

-t, --instance-type <instance_type>

The type of SageMaker ML instance on which to deploy the model. For a list of supported instance types, see https://aws.amazon.com/sagemaker/pricing/instance-types/.

-c, --instance-count <instance_count>

The number of SageMaker ML instances on which to deploy the model

-v, --vpc-config <vpc_config>

Path to a file containing a JSON-formatted VPC configuration. This configuration will be used when creating the new SageMaker model associated with this application. For more information, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_VpcConfig.html

-f, --flavor <flavor>

The name of the flavor to use for deployment. Must be one of the following: [‘python_function’, ‘mleap’]. If unspecified, a flavor will be automatically selected from the model’s available flavors.

--async

If specified, this command will return immediately after starting the deployment process. It will not wait for the deployment process to complete. The caller is responsible for monitoring the deployment process via native SageMaker APIs or the AWS console.

--timeout <timeout>

If the command is executed synchronously, the deployment process will return after the specified number of seconds if no definitive result (success or failure) is achieved. Once the function returns, the caller is responsible for monitoring the health and status of the pending deployment via native SageMaker APIs or the AWS console. If the command is executed asynchronously using the –async flag, this value is ignored.

run-local

Serve model locally running in a Sagemaker-compatible Docker container.

mlflow sagemaker run-local [OPTIONS]

Options

-m, --model-uri <model_uri>

URI to the model. A local path, a ‘runs:/’ URI, or a remote storage URI (e.g., an ‘s3://’ URI). For more information about supported remote URIs for model artifacts, see https://mlflow.org/docs/latest/tracking.html#artifact-stores [required]

-p, --port <port>

Server port. [default: 5000]

-i, --image <image>

Docker image name

-f, --flavor <flavor>

The name of the flavor to use for local serving. Must be one of the following: [‘python_function’, ‘mleap’]. If unspecified, a flavor will be automatically selected from the model’s available flavors.

server

Run the MLflow tracking server.

The server which listen on http://localhost:5000 by default, and only accept connections from the local machine. To let the server accept connections from other machines, you will need to pass --host 0.0.0.0 to listen on all network interfaces (or a specific interface address).

mlflow server [OPTIONS]

Options

--backend-store-uri <backend_store_uri>

URI to which to persist experiment and run data. Acceptable URIs are SQLAlchemy-compatible database connection strings (e.g. ‘sqlite:///path/to/file.db’) or local filesystem URIs (e.g. ‘file:///absolute/path/to/directory’). By default, data will be logged to the ./mlruns directory.

--default-artifact-root <default_artifact_root>

Local or S3 URI to store artifacts, for new experiments. Note that this flag does not impact already-created experiments. Default: Within file store, if a file:/ URI is provided. If a sql backend is used, then this option is required.

-h, --host <host>

The network address to listen on (default: 127.0.0.1). Use 0.0.0.0 to bind to all addresses if you want to access the tracking server from other machines.

-p, --port <port>

The port to listen on (default: 5000).

-w, --workers <workers>

Number of gunicorn worker processes to handle requests (default: 4).

--static-prefix <static_prefix>

A prefix which will be prepended to the path of all static paths.

--gunicorn-opts <gunicorn_opts>

Additional command line options forwarded to gunicorn processes.

--waitress-opts <waitress_opts>

Additional command line options for waitress-serve.

ui

Launch the MLflow tracking UI for local viewing of run results. To launch a production server, use the “mlflow server” command instead.

The UI will be visible at http://localhost:5000 by default.

mlflow ui [OPTIONS]

Options

--backend-store-uri <backend_store_uri>

URI to which to persist experiment and run data. Acceptable URIs are SQLAlchemy-compatible database connection strings (e.g. ‘sqlite:///path/to/file.db’) or local filesystem URIs (e.g. ‘file:///absolute/path/to/directory’). By default, data will be logged to the ./mlruns directory.

--default-artifact-root <default_artifact_root>

Path to local directory to store artifacts, for new experiments. Note that this flag does not impact already-created experiments. Default: ./mlruns

-p, --port <port>

The port to listen on (default: 5000).