1  # Getting Started with Workspaces
  2  
  3  This guide walks through setting up and using MLflow workspaces to organize teams and projects on a shared MLflow server.
  4  
  5  ## Prerequisites
  6  
  7  Before enabling workspaces, ensure you have:
  8  
  9  - A SQL database backend (PostgreSQL, MySQL, SQLite, or MSSQL)
 10  - MLflow server configured with a backend store URI
 11  - A configured `--default-artifact-root`
 12  - Database migrations applied via `mlflow db upgrade`
 13  
 14  :::warning File-based backends not supported
 15  
 16  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.
 17  
 18  :::
 19  
 20  :::warning Custom experiment artifact locations are not supported
 21  
 22  For security, experiments cannot override artifact locations when workspaces are enabled. Workspace
 23  stores can customize the artifact location at the workspace level.
 24  
 25  :::
 26  
 27  ## Step 1: Start MLflow with Workspaces Enabled
 28  
 29  Start the MLflow server with the `--enable-workspaces` flag:
 30  
 31  ```bash
 32  mlflow server \
 33    --backend-store-uri postgresql://user:pass@localhost/mlflow \
 34    --default-artifact-root s3://mlflow-artifacts \
 35    --enable-workspaces
 36  ```
 37  
 38  Or use the environment variable:
 39  
 40  ```bash
 41  export MLFLOW_ENABLE_WORKSPACES=true
 42  mlflow server \
 43    --backend-store-uri postgresql://user:pass@localhost/mlflow \
 44    --default-artifact-root s3://mlflow-artifacts
 45  ```
 46  
 47  When the server starts, it will:
 48  
 49  1. Verify that both tracking and model registry stores support workspaces
 50  2. Verify `--default-artifact-root` is set and validate it does not conflict with reserved workspace paths
 51  3. Enforce workspace scoping for API and UI requests
 52  
 53  ## Step 2: Create a Workspace
 54  
 55  As an administrator, create a workspace using the MLflow SDK:
 56  
 57  ```python
 58  import mlflow
 59  
 60  mlflow.set_tracking_uri("http://localhost:5000")
 61  
 62  # Create a new workspace
 63  workspace = mlflow.create_workspace(
 64      name="team-a",
 65      description="Workspace for Team A machine learning projects",
 66      # Optional: override artifact root for this workspace
 67      default_artifact_root="s3://team-a-artifacts",
 68  )
 69  print(f"Created workspace: {workspace.name}")
 70  ```
 71  
 72  You can also use the REST API directly:
 73  
 74  ```bash
 75  curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces \
 76    -H "Content-Type: application/json" \
 77    -d '{
 78      "name": "team-a",
 79      "description": "Workspace for Team A machine learning projects",
 80      "default_artifact_root": "s3://team-a-artifacts"
 81    }'
 82  ```
 83  
 84  ### Workspace Naming Rules
 85  
 86  Workspace names must follow DNS-safe conventions:
 87  
 88  - Pattern: `^(?!.*--)[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
 89  - Minimum length: 2 characters
 90  - Maximum length: 63 characters
 91  - Lowercase alphanumeric with hyphens allowed in the middle
 92  - Cannot start or end with a hyphen
 93  - Consecutive hyphens (`--`) are not allowed
 94  
 95  Reserved names that cannot be used:
 96  
 97  - `default` - Reserved for legacy single-tenant resources
 98  - `workspaces` - Prevents path conflicts
 99  - `api`, `ajax-api`, `static-files` - Prevent conflicts with server routes
100  
101  ## Step 3: Grant Workspace Permissions (Optional)
102  
103  If authentication is enabled, admins can grant workspace-level permissions. These act as a convenient fallback when users don't have explicit resource permissions:
104  
105  ```bash
106  curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions \
107    -H "Content-Type: application/json" \
108    -d '{
109      "username": "alice",
110      "permission": "MANAGE"
111    }'
112  ```
113  
114  Available permission levels:
115  
116  - `READ` - View resources
117  - `USE` - View and invoke resources such as AI Gateway endpoints
118  - `EDIT` - View and modify resources
119  - `MANAGE` - Full control including permissions
120  - `NO_PERMISSIONS` - Explicitly deny access
121  
122  Workspace permissions apply to all resource types (experiments, registered models, prompts, and AI
123  Gateway resources like API keys, model definitions, and endpoints) within the workspace.
124  
125  ## Step 4: Use Workspaces from Python Client
126  
127  Set the active workspace before performing operations:
128  
129  ```python
130  import mlflow
131  
132  # Configure tracking URI
133  mlflow.set_tracking_uri("http://localhost:5000")
134  
135  # Set active workspace
136  mlflow.set_workspace("team-a")
137  
138  # Create experiment (automatically scoped to team-a)
139  experiment_id = mlflow.create_experiment("my-experiment")
140  
141  # Start a run
142  with mlflow.start_run(experiment_id=experiment_id):
143      mlflow.log_param("learning_rate", 0.01)
144      mlflow.log_metric("accuracy", 0.95)
145  
146  print(f"Logged run in workspace: {mlflow.get_workspace()}")
147  ```
148  
149  ## Managing Workspaces
150  
151  ### List Workspaces
152  
153  ```python
154  import mlflow
155  
156  mlflow.set_tracking_uri("http://localhost:5000")
157  
158  # List all accessible workspaces
159  workspaces = mlflow.list_workspaces()
160  for workspace in workspaces:
161      print(f"{workspace.name}: {workspace.description}")
162  ```
163  
164  When authentication is enabled, this returns only workspaces accessible to the authenticated user.
165  
166  ### Get Workspace Details
167  
168  ```python
169  from mlflow import MlflowClient
170  
171  client = MlflowClient("http://localhost:5000")
172  workspace = client.get_workspace("team-a")
173  print(f"Workspace: {workspace.name}")
174  print(f"Description: {workspace.description}")
175  ```
176  
177  ### Update Workspace Description
178  
179  ```python
180  import mlflow
181  
182  mlflow.set_tracking_uri("http://localhost:5000")
183  
184  # Update workspace description
185  updated = mlflow.update_workspace(
186      name="team-a",
187      description="Updated description for Team A",
188      # Optional: update (or clear) the workspace artifact root override
189      default_artifact_root="s3://team-a-artifacts",
190  )
191  print(f"Updated: {updated.name}")
192  ```
193  
194  :::note Workspace names are immutable
195  
196  Workspace names cannot be changed after creation. Only the description can be updated.
197  
198  :::
199  
200  ### Delete Workspace
201  
202  A workspace can only be deleted if it contains no resources:
203  
204  ```python
205  import mlflow
206  
207  mlflow.set_tracking_uri("http://localhost:5000")
208  
209  # Delete empty workspace
210  mlflow.delete_workspace("team-a")
211  ```
212  
213  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.
214  
215  ### REST API Alternatives
216  
217  All workspace management operations are also available via REST API:
218  
219  ```bash
220  # List workspaces
221  curl http://localhost:5000/api/3.0/mlflow/workspaces
222  
223  # Get workspace
224  curl http://localhost:5000/api/3.0/mlflow/workspaces/team-a
225  
226  # Update workspace
227  curl -X PATCH http://localhost:5000/api/3.0/mlflow/workspaces/team-a \
228    -H "Content-Type: application/json" \
229    -d '{"description": "Updated description"}'
230  
231  # Delete workspace
232  curl -X DELETE http://localhost:5000/api/3.0/mlflow/workspaces/team-a
233  ```
234  
235  ## Using REST APIs with Workspaces
236  
237  REST API calls specify the workspace via the `X-MLFLOW-WORKSPACE` header:
238  
239  ```bash
240  # Create experiment in team-a workspace
241  curl -X POST http://localhost:5000/api/2.0/mlflow/experiments/create \
242    -H "Content-Type: application/json" \
243    -H "X-MLFLOW-WORKSPACE: team-a" \
244    -d '{"name": "my-experiment"}'
245  
246  # List experiments in team-a workspace
247  curl http://localhost:5000/api/2.0/mlflow/experiments/list \
248    -H "X-MLFLOW-WORKSPACE: team-a"
249  ```
250  
251  ## Troubleshooting
252  
253  ### Error: "Active workspace is required"
254  
255  This error occurs when calling MLflow APIs without setting a workspace and the provider doesn't support a default workspace. Solution:
256  
257  ```python
258  mlflow.set_workspace("your-workspace-name")
259  ```
260  
261  Or set the environment variable:
262  
263  ```bash
264  export MLFLOW_WORKSPACE=your-workspace-name
265  ```
266  
267  ## Next Steps
268  
269  - [Configuration](../configuration) - Learn about server configuration options
270  - [Workspace Providers](../workspace-providers) - Understand the provider architecture
271  - [Permissions](../permissions) - Configure workspace-scoped access control