Skip to main content

Getting Started with Workspaces

This guide walks through setting up and using MLflow workspaces to organize teams and projects on a shared MLflow server.

Prerequisites​

Before enabling workspaces, ensure you have:

  • A SQL database backend (PostgreSQL, MySQL, SQLite, or MSSQL)
  • MLflow server configured with a backend store URI
  • A configured --default-artifact-root
  • Database migrations applied via mlflow db upgrade
File-based backends not supported

Workspaces require a SQL database backend store. File-based tracking and model registry stores (for example ./mlruns or file:///...) are not supported when workspaces are enabled.

Custom experiment artifact locations are not supported

For security, experiments cannot override artifact locations when workspaces are enabled. Workspace stores can customize the artifact location at the workspace level.

Step 1: Start MLflow with Workspaces Enabled​

Start the MLflow server with the --enable-workspaces flag:

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

Or use the environment variable:

bash
export MLFLOW_ENABLE_WORKSPACES=true
mlflow server \
  --backend-store-uri postgresql://user:pass@localhost/mlflow \
  --default-artifact-root s3://mlflow-artifacts

When the server starts, it will:

  1. Verify that both tracking and model registry stores support workspaces
  2. Verify --default-artifact-root is set and validate it does not conflict with reserved workspace paths
  3. Enforce workspace scoping for API and UI requests

Step 2: Create a Workspace​

As an administrator, create a workspace using the MLflow SDK:

python
import mlflow

mlflow.set_tracking_uri("http://localhost:5000")

# Create a new workspace
workspace = mlflow.create_workspace(
    name="team-a",
    description="Workspace for Team A machine learning projects",
    # Optional: override artifact root for this workspace
    default_artifact_root="s3://team-a-artifacts",
)
print(f"Created workspace: {workspace.name}")

You can also use the REST API directly:

bash
curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "team-a",
    "description": "Workspace for Team A machine learning projects",
    "default_artifact_root": "s3://team-a-artifacts"
  }'

Workspace Naming Rules​

Workspace names must follow DNS-safe conventions:

  • Pattern: ^(?!.*--)[a-z0-9]([-a-z0-9]*[a-z0-9])?$
  • Minimum length: 2 characters
  • Maximum length: 63 characters
  • Lowercase alphanumeric with hyphens allowed in the middle
  • Cannot start or end with a hyphen
  • Consecutive hyphens (--) are not allowed

Reserved names that cannot be used:

  • default - Reserved for legacy single-tenant resources
  • workspaces - Prevents path conflicts
  • api, ajax-api, static-files - Prevent conflicts with server routes

Step 3: Grant Workspace Permissions (Optional)​

If authentication is enabled, admins can grant workspace-level permissions. These act as a convenient fallback when users don't have explicit resource permissions:

bash
curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "permission": "MANAGE"
  }'

Available permission levels:

  • READ - View resources
  • USE - View and invoke resources such as AI Gateway endpoints
  • EDIT - View and modify resources
  • MANAGE - Full control including permissions
  • NO_PERMISSIONS - Explicitly deny access

Workspace permissions apply to all resource types (experiments, registered models, prompts, and AI Gateway resources like API keys, model definitions, and endpoints) within the workspace.

Step 4: Use Workspaces from Python Client​

Set the active workspace before performing operations:

python
import mlflow

# Configure tracking URI
mlflow.set_tracking_uri("http://localhost:5000")

# Set active workspace
mlflow.set_workspace("team-a")

# Create experiment (automatically scoped to team-a)
experiment_id = mlflow.create_experiment("my-experiment")

# Start a run
with mlflow.start_run(experiment_id=experiment_id):
    mlflow.log_param("learning_rate", 0.01)
    mlflow.log_metric("accuracy", 0.95)

print(f"Logged run in workspace: {mlflow.get_workspace()}")

Managing Workspaces​

List Workspaces​

python
import mlflow

mlflow.set_tracking_uri("http://localhost:5000")

# List all accessible workspaces
workspaces = mlflow.list_workspaces()
for workspace in workspaces:
    print(f"{workspace.name}: {workspace.description}")

When authentication is enabled, this returns only workspaces accessible to the authenticated user.

Get Workspace Details​

python
from mlflow import MlflowClient

client = MlflowClient("http://localhost:5000")
workspace = client.get_workspace("team-a")
print(f"Workspace: {workspace.name}")
print(f"Description: {workspace.description}")

Update Workspace Description​

python
import mlflow

mlflow.set_tracking_uri("http://localhost:5000")

# Update workspace description
updated = mlflow.update_workspace(
    name="team-a",
    description="Updated description for Team A",
    # Optional: update (or clear) the workspace artifact root override
    default_artifact_root="s3://team-a-artifacts",
)
print(f"Updated: {updated.name}")
Workspace names are immutable

Workspace names cannot be changed after creation. Only the description can be updated.

Delete Workspace​

A workspace can only be deleted if it contains no resources:

python
import mlflow

mlflow.set_tracking_uri("http://localhost:5000")

# Delete empty workspace
mlflow.delete_workspace("team-a")

The delete operation will fail if the workspace contains any experiments, registered models, or prompts. Child resources (runs, model versions) count via their parent associations.

REST API Alternatives​

All workspace management operations are also available via REST API:

bash
# List workspaces
curl http://localhost:5000/api/3.0/mlflow/workspaces

# Get workspace
curl http://localhost:5000/api/3.0/mlflow/workspaces/team-a

# Update workspace
curl -X PATCH http://localhost:5000/api/3.0/mlflow/workspaces/team-a \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

# Delete workspace
curl -X DELETE http://localhost:5000/api/3.0/mlflow/workspaces/team-a

Using REST APIs with Workspaces​

REST API calls specify the workspace via the X-MLFLOW-WORKSPACE header:

bash
# Create experiment in team-a workspace
curl -X POST http://localhost:5000/api/2.0/mlflow/experiments/create \
  -H "Content-Type: application/json" \
  -H "X-MLFLOW-WORKSPACE: team-a" \
  -d '{"name": "my-experiment"}'

# List experiments in team-a workspace
curl http://localhost:5000/api/2.0/mlflow/experiments/list \
  -H "X-MLFLOW-WORKSPACE: team-a"

Troubleshooting​

Error: "Active workspace is required"​

This error occurs when calling MLflow APIs without setting a workspace and the provider doesn't support a default workspace. Solution:

python
mlflow.set_workspace("your-workspace-name")

Or set the environment variable:

bash
export MLFLOW_WORKSPACE=your-workspace-name

Next Steps​