Great questions — here’s how naming works for deployments in Prefect 3.x and what we recommend. What

flow_name

and

name

mean - `flow_name`: The name of the flow this deployment belongs to. In YAML it’s human-readable; on the server it resolves to the flow’s ID. - `name`: The deployment’s name within that flow. How deployments are referenced - You refer to a deployment as

flow_name/name

(e.g.,

my-flow/prod

). - The CLI and API use this composite to find a deployment. Why both exist - Yes — because you can create multiple deployments for the same flow (e.g., dev vs prod, different schedules, different work pools/runners, etc.). The pair

(flow_id, name)

is the unique key in the database. - In the UI and CLI, deployments are grouped under their flow. You can list by flow with

prefect deployments ls --flow-name "<flow name>"

. Allowed characters and casing - Deployment names cannot contain:

/

,

%

,

&

,

>

,

<

. - Spaces and capitalization are allowed, and comparisons are case-sensitive. - Practically: spaces mean you’ll need quotes in CLI commands (e.g.,

prefect deployments run "My Flow/Prod Run"

). Recommendations (best practice) - Use lowercase, hyphenated “slugs” for deployment names, e.g.,

dev

,

prod

,

daily-10am

. This avoids quoting in the CLI and keeps things readable. - Keep

flow_name

exactly equal to your flow’s

flow.name

. If you rename the flow, the reference string changes (the deployment stays linked by ID, but the

flow_name/name

string you type will change). - Since you have many flows and only dev/prod differences, reuse the same deployment names across flows (e.g., every flow has

dev

and

prod

). That works because uniqueness is per flow, not global. Example

yaml
deployments:
  - flow_name: my-data-pipeline
    name: dev
    # pull/source and runner specifics here

  - flow_name: my-data-pipeline
    name: prod
    # different pull/source and runner here

  - flow_name: another-flow
    name: dev

  - flow_name: another-flow
    name: prod

Key details (for reference) - Uniqueness: deployments are unique by

(flow_id, name)

, not globally. - Reference format:

<flow_name>/<deployment_name>

. - UI grouping: deployments are shown under their parent flow. Links - CLI: deployments (inspect/run/delete/schedule): CLI: deployments - Name validation (forbidden characters): Name validation code - Uniqueness constraint in the ORM: Unique constraint code - Server lookup by flow_name/name: Read deployment by name If you want, share a snippet of your

prefect.yaml

, and I can suggest concrete names and structure tailored to your setup.

Short answer - No conflict. The flow’s name comes from your Python code, not from prefect.yaml. - The value set in the

@flow(name="...")

decorator always wins at deploy time. - The top-level

name

in prefect.yaml is just project metadata (ignored by the CLI for deployment purposes). - Any

deployments[].flow_name

you put in prefect.yaml is overwritten with the actual

flow.name

loaded from the entrypoint. Details - During

prefect deploy

, Prefect loads the flow object from the

entrypoint

and then sets the deployment’s

flow_name

to

flow.name

unconditionally. If you had a different

flow_name

in YAML, it’s ignored. - The top-level

prefect.yaml

name

field is not used to set a flow’s name; it’s currently just metadata. Recommendations - Define your flow’s name once in code via

@flow(name="...")

. If you don’t specify it, Prefect derives it from the function name. - In YAML, don’t rely on

flow_name

to control naming; treat it as informational only.