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-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.

SettingDefaultDescription
grant_default_workspace_accessfalseWhen 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_size10000Maximum entries in the resource-to-workspace lookup cache used for permission checks.
workspace_cache_ttl_seconds3600TTL 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.
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​

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​