Skip to main content

Workspace Configuration

Reference for the core flags, env vars, and startup checks for workspace mode. For setup and end-to-end flows, see Getting Started. For provider details and artifact routing options, see Workspace Providers.

Server Configuration (enable/disable)​

Enable workspaces with the flag:

bash
mlflow server \
  --backend-store-uri postgresql://user:pass@localhost/mlflow \
  --default-artifact-root s3://mlflow-artifacts \
  --enable-workspaces

Or with env vars:

bash
export MLFLOW_ENABLE_WORKSPACES=true
mlflow server \
  --backend-store-uri ... \
  --default-artifact-root ...

Disable by restarting without --enable-workspaces after moving all resources into the default workspace.

Admin Utility: migrate to default workspace​

To move all workspace-scoped resources into default to disable workspaces, use:

bash
mlflow db migrate-to-default-workspace <database_uri>

By default, the command prints the rows to be moved and asks for confirmation. Use -y to skip the prompt.

Run a dry run first to surface conflicts and see how many rows will be updated:

bash
mlflow db migrate-to-default-workspace <database_uri> --dry-run

Use --verbose to list all conflicts instead of a truncated sample.

Client Workspace Selection (summary)​

  • Explicit: mlflow.set_workspace("team-a")
  • Env var: MLFLOW_WORKSPACE=team-a
  • Provider default: get_default_workspace() (SQL provider returns default)

Clients send X-MLFLOW-WORKSPACE on REST calls; UI AJAX routes remain the same (/api, /ajax-api).

Startup Validation (when --enable-workspaces)​

  • Tracking and registry stores must report supports_workspaces() == True
  • Workspace provider resolved (defaults to SQL-backed provider if none given)
  • Reserved default workspace exists (created by migration)
  • With --serve-artifacts, proxied artifact paths for non-default workspaces must include workspaces/<workspace>/...; legacy unprefixed paths remain valid for default.

Admin preflight for artifact roots​

Before enabling workspaces, confirm that existing experiment artifact locations do not already live under the reserved <default_artifact_root>/workspaces/<workspace>/... path unless they match the workspace layout you intend to use. If they do, move or rename those artifact roots first to avoid collisions.

Artifact Behavior​

  • By default, new experiments land under <default_artifact_root>/workspaces/<workspace>/<experiment_id>; runs inherit that path.
  • Existing experiments/runs keep their stored locations (legacy unprefixed paths under default continue to work).
  • To override the artifact root for a specific workspace, set default_artifact_root on the workspace (via mlflow.create_workspace(...) / mlflow.update_workspace(...) or the workspace REST API). When set, MLflow uses <workspace_default_artifact_root>/<experiment_id> (no /workspaces/<workspace> prefix) for new experiments in that workspace.

API Limitations​

  • create_experiment() disallows artifact_location while workspaces are enabled; MLflow assigns workspace-scoped locations.

Detecting Workspace Support Programmatically​

  • Call GET /api/3.0/mlflow/server-features to check workspaces_enabled.
  • The endpoint is reachable without a workspace header; a 404 indicates an older server without workspace support.

Environment Variables​

VariableDescriptionDefault
MLFLOW_ENABLE_WORKSPACESEnable workspace modefalse
MLFLOW_WORKSPACEActive workspace for client operationsNone
MLFLOW_WORKSPACE_STORE_URIOverride the workspace provider URI; falls back to the resolved tracking URINone (falls back to resolved tracking URI)

MLFLOW_WORKSPACE chooses the target workspace. MLFLOW_WORKSPACE_STORE_URI selects where the workspace catalog lives (and which provider to use), not which workspace; if unset, the tracking URI is reused. Providers are discovered via the mlflow.workspace_provider entry point.

Next Steps​