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.

Admin Utility: move resources between workspaces

To selectively move resources from one workspace to another, use:

bash

mlflow db move-resources <database_uri> \
  --from <source_workspace> --to <target_workspace> \
  --resource-type <table_name>

The --resource-type value is the database table name (experiments, registered_models, evaluation_datasets, webhooks, jobs).

:::note Gateway resources not supported Gateway resources (secrets, endpoints, model_definitions, budget_policies) are not supported by this command because they have inter-table foreign-key dependencies that make moving them independently unsafe. :::

Filter which resources to move by name or tag:

bash

# Move specific experiments by name
mlflow db move-resources <database_uri> \
  --from default --to team-a --resource-type experiments \
  --name training-v1 --name training-v2

# Move experiments matching tags (AND logic when multiple tags are given)
mlflow db move-resources <database_uri> \
  --from default --to team-a --resource-type experiments \
  --tag team=team-a --tag env=prod

When neither --name nor --tag is specified, all resources of the given type in the source workspace are moved. Tag filtering is supported for experiments and registered_models only.

Use --dry-run to preview what would be moved without making changes, and -y to skip the confirmation prompt. The command aborts if any resource name would conflict with an existing resource in the target workspace.

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-info to check workspaces_enabled.
• The endpoint is reachable without a workspace header; a 404 indicates an older server without workspace support.

Authentication Configuration for Workspaces

When using workspaces with basic-auth (--app-name basic-auth), additional settings in the auth config file (basic_auth.ini) control workspace-level permission behavior.

Setting	Default	Description
grant_default_workspace_access	false	When true, all users inherit default_permission for the reserved default workspace (pre-workspaces behavior). When false, users need explicit workspace permissions even for the default workspace.
workspace_cache_max_size	10000	Maximum entries in the resource-to-workspace lookup cache used for permission checks.
workspace_cache_ttl_seconds	3600	TTL in seconds for cached resource-to-workspace lookups.

grant_default_workspace_access

This setting controls how the reserved default workspace interacts with default_permission.

• false (default): The default workspace does not inherit default_permission. Users must be granted explicit workspace permissions to access resources, even in the default workspace. This is the most secure option for new deployments.
• true: The default workspace inherits default_permission for all authenticated users. The default workspace also appears in mlflow.list_workspaces() results for every user.

:::warning Recommendation for existing instances If you are enabling workspaces on an existing MLflow instance that already uses basic-auth, set grant_default_workspace_access = true for backwards compatibility. Without this, all existing resources (which live in the default workspace) will become inaccessible to non-admin users who lack explicit workspace permissions. :::

Example configuration:

basic_auth.ini

ini

[mlflow]
default_permission = READ
database_uri = sqlite:///basic_auth.db
admin_username = admin
admin_password = password1234
authorization_function = mlflow.server.auth:authenticate_request_basic_auth
# Default secure setting for new deployments; for existing instances upgrading to workspaces,
# set this to true for backwards compatibility (see note above).
grant_default_workspace_access = false
workspace_cache_max_size = 10000
workspace_cache_ttl_seconds = 3600

Environment Variables

Variable	Description	Default
MLFLOW_ENABLE_WORKSPACES	Enable workspace mode	false
MLFLOW_WORKSPACE	Active workspace for client operations	None
MLFLOW_WORKSPACE_STORE_URI	Override the workspace provider URI; falls back to the resolved tracking URI	None (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

• Getting Started - Step-by-step enablement
• Workspace Providers - Provider selection and artifact routing
• Permissions - Configure access control
• Troubleshooting - Common issues and fixes