Environment:Mlflow Mlflow MLflow Server Environment

Knowledge Sources	MLflow MLflow CLI
Domains	Infrastructure, Web_Serving
Last Updated	2026-02-13 20:00 GMT

Overview

Server environment for running the MLflow tracking server with Flask/FastAPI backend, uvicorn/gunicorn ASGI/WSGI server, and optional database backends.

Description

This environment provides the runtime for the MLflow tracking server, which serves the experiment tracking UI and REST API. The server can run with three different WSGI/ASGI server backends depending on the platform: uvicorn (default, cross-platform), gunicorn (Unix-like only), or waitress (Windows only). The server supports multiple backend stores including file-based, SQLite, PostgreSQL, MySQL, and MSSQL. For production deployments, a database backend with PostgreSQL or MySQL is recommended.

Usage

Use this environment when deploying the MLflow tracking server or the MLflow model scoring server. It is the mandatory prerequisite for running `mlflow server`, `mlflow ui`, or `mlflow models serve` commands.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	gunicorn Unix-only; waitress Windows-only
Python	>= 3.10	Same as core MLflow
Network	Port 5000 (default)	Configurable via `--port` flag
Disk	1GB+ SSD	For file-based backend store; less for DB backend

Dependencies

System Packages

`postgresql` (optional, for PostgreSQL backend)
`mysql-server` (optional, for MySQL backend)

Python Packages (Server Core)

`Flask` < 4
`Flask-CORS` < 7
`fastapi` < 1
`uvicorn` < 1 (default ASGI server)
`gunicorn` < 26 (Unix-like alternative)
`waitress` < 4 (Windows alternative)
`sqlalchemy` >= 1.4.0, < 3
`alembic` < 2, != 1.10.0
`graphene` < 4

Optional Database Drivers

`psycopg2-binary` (PostgreSQL)
`PyMySQL` (MySQL)
`pymssql` (MSSQL)

Credentials

The following environment variables configure the server:

`MLFLOW_TRACKING_URI`: Backend store URI (e.g., `sqlite:///mlflow.db`, `postgresql://...`)
`MLFLOW_FLASK_SERVER_SECRET_KEY`: Secret key for Flask CSRF protection
`MLFLOW_SERVER_CORS_ALLOWED_ORIGINS`: Comma-separated CORS allowed origins
`MLFLOW_SERVER_ALLOWED_HOSTS`: Comma-separated allowed Host headers
`MLFLOW_AUTH_CONFIG_PATH`: Path to authentication configuration file
`MLFLOW_SQLALCHEMYSTORE_POOL_SIZE`: SQLAlchemy connection pool size
`MLFLOW_SQLALCHEMYSTORE_POOL_RECYCLE`: Connection recycle time (seconds)
`MLFLOW_SQLALCHEMYSTORE_MAX_OVERFLOW`: Max overflow connections

For MySQL with SSL:

`MLFLOW_MYSQL_SSL_CA`: SSL CA certificate path
`MLFLOW_MYSQL_SSL_CERT`: SSL certificate path
`MLFLOW_MYSQL_SSL_KEY`: SSL key path

Quick Install

# Install MLflow with PostgreSQL support
pip install mlflow psycopg2-binary

# Install MLflow with MySQL support
pip install mlflow PyMySQL

# Start the server with SQLite backend
mlflow server --backend-store-uri sqlite:///mlflow.db --default-artifact-root ./mlruns

# Start with PostgreSQL backend
mlflow server --backend-store-uri postgresql://user:pass@host/dbname

# Start in development mode (auto-reload)
mlflow server --dev

Code Evidence

Server command with mutual exclusivity of server options from `mlflow/cli/__init__.py:297-349`:

@cli.command("server")
@click.option("--gunicorn-opts", default=None)
@click.option("--waitress-opts", default=None)
@click.option("--uvicorn-opts", default=None)
@click.option("--dev", is_flag=True, default=False)
def server(...):
    # Validates mutual exclusivity of server options

Scoring server uvicorn command from `mlflow/pyfunc/scoring_server/__init__.py:605-632`:

# Uses uvicorn: uvicorn mlflow.pyfunc.scoring_server.app:app
# Supports --workers, --host, --port parameters
# Request timeout via MLFLOW_SCORING_SERVER_REQUEST_TIMEOUT

SQLAlchemy pool configuration from `mlflow/environment_variables.py`:

MLFLOW_SQLALCHEMYSTORE_POOL_SIZE = _EnvironmentVariable(
    "MLFLOW_SQLALCHEMYSTORE_POOL_SIZE", int, None
)
MLFLOW_SQLALCHEMYSTORE_POOL_RECYCLE = _EnvironmentVariable(
    "MLFLOW_SQLALCHEMYSTORE_POOL_RECYCLE", int, None
)
MLFLOW_SQLALCHEMYSTORE_MAX_OVERFLOW = _EnvironmentVariable(
    "MLFLOW_SQLALCHEMYSTORE_MAX_OVERFLOW", int, None
)

Common Errors

Error Message	Cause	Solution
`ModuleNotFoundError: No module named 'psycopg2'`	PostgreSQL driver not installed	`pip install psycopg2-binary`
`OperationalError: could not connect to server`	Database server not running	Start PostgreSQL/MySQL and verify connection string
`Address already in use`	Port 5000 already bound	Use `--port` flag to specify a different port
`gunicorn: not found`	Trying to use gunicorn on Windows	Use `--waitress-opts` on Windows or default uvicorn

Compatibility Notes

Windows: Cannot use gunicorn. Uses waitress as WSGI server. Uvicorn is the default and works cross-platform.
Development mode: `--dev` flag enables auto-reload via uvicorn, useful for frontend development.
File-based backend: Deprecated for model registry as of February 2026. Use database backends for new projects.
Docker Compose: A reference `docker-compose.yml` is provided with PostgreSQL 15 and MinIO (S3-compatible) for production-like deployments.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment