Great question — naming can make or break clarity at scale. Short answer - In Prefect 3.x, deployment names do NOT have to be globally unique. They only need to be unique per flow. - Flows must have unique names within a workspace. - You always address a deployment as

flow_name/deployment_name

. References - Concepts: Deployments in Prefect 3.x - Running deployments (shows the addressing format): Run deployments - API route (confirms lookup by flow_name/deployment_name): GET /api/deployments/name/{flow_name}/{deployment_name} Recommended naming conventions - Flow names (must be unique): describe the business process or dataset, e.g.

ingest-orders

,

sync-salesforce

. - Deployment names (unique per flow): encode the “variant” of that flow you’re running. Common fields: - env:

dev

,

stg

,

prod

- tenant/client:

client-acme

- region (optional):

us-east

,

eu-west

- trigger/schedule (optional):

manual

,

hourly

,

event

Patterns that work well - kebab-case, lowercase, stable field order, avoid slashes - Examples for a shared flow

ingest-orders

across multiple clients: -

prod-client-acme

-

prod-client-zen

-

stg-client-acme

- Full addresses:

ingest-orders/prod-client-acme

,

ingest-orders/stg-client-acme

Two common approaches for multi-client setups 1) One deployment per client (most explicit) - Clear ownership and independent schedules/params - Example:

from prefect import flow

  @flow
  def ingest_orders(client: str):
      ...

  for client in ["acme", "zen"]:
      ingest_orders.deploy(
          name=f"prod-client-{client}",
          work_pool_name="prod-pool",
          parameters={"client": client},
      )

You’ll run as:

ingest-orders/prod-client-acme

2) Single shared deployment, pass client at runtime (fewer deployments) - Good when you have many clients or similar config

from prefect.deployments import run_deployment

  # One deployment to rule them all
  # name = "prod-shared" (for flow "ingest-orders")

  # Trigger per client
  run_deployment(
      name="ingest-orders/prod-shared",
      parameters={"client": "acme"}
  )

Hybrid: If you need a few environment-specific deployments, use something like

prod-shared

and

stg-shared

, then pass

client

per run. Rule of thumb - If each client needs distinct infra, schedules, or secrets: per-client deployments. - If clients share most config and you just vary one or two parameters: one shared deployment and pass parameters. If you can share a bit more about: - how many clients you have, - whether their schedules/infra differ, - and how you trigger runs (CLI, API, events), I can recommend a concrete naming schema tailored to your setup.