Short answer - flow_version = version of the flow code that actually ran - deployment_version = version of the deployment configuration that launched the run - Defaulting: when you create a deployment and do not set a deployment version, Prefect will default the deployment_version to the flow’s version at that time. The reverse is not true. - Which to use: use flow_version to track code lineage; use deployment_version to track/promote/roll back deployment config changes (especially in Prefect Cloud). Most teams benefit from setting both explicitly. Details (Prefect 3.x) - flow_version - What it is: A string on the Flow object that’s captured onto each Flow Run as flow_version. - How it’s set: - If you pass version in the @flow decorator, that value is used. - If you don’t, Prefect will try to derive a version from the flow’s source file (e.g., a file hash). If it can’t (e.g., notebook/REPL), it will be None. - Where you’ll see it: On each run detail and via runtime at

prefect.runtime.flow_run.flow_version

. - Source references: - Flow decorator (shows the version parameter): https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py - Runtime fields (includes flow_version): https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py - deployment_version - What it is: A string on the Deployment object that’s captured onto each Flow Run launched by that deployment as deployment_version. - How it’s set: - If you pass version to

.deploy(...)

(or

.to_deployment(...)

), that value is used. - If you don’t pass it, Prefect sets the deployment’s version to the flow’s current version (i.e., deployment_version defaults to flow_version at deploy time). - If the flow had no version, the deployment_version will be None unless you set it. - Where you’ll see it: On runs started by that deployment; in Prefect Cloud, you also get deployment version history with rollbacks/promotions. - Source reference (defaulting behavior in runner): https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py Behavior notes - Runs launched by a deployment record both values: - flow_run.flow_version = the flow’s version at run creation - flow_run.deployment_version = the deployment’s version - Ad-hoc runs (no deployment) will have flow_version set (if available) and deployment_version = None. - There is no bidirectional fallback at run time: deployment_version does not become flow_version on the run unless it was set on the deployment; flow_version never defaults to deployment_version. Recommendations - Prefer setting both explicitly and independently: - In code, set @flow(version="1.2.3") to track code lineage across all runs. - In deployments, set version="deploy-2026-03-12" (or similar) when you change deployment config (work pool, job variables, entrypoint, default parameters, etc.). - If you only pick one: - Use flow_version to attribute runs to specific code (debugging, reproducibility). - Use deployment_version when you operationally manage promotion/rollback of deployment configs (especially in Cloud). Example

from prefect import flow

@flow(version="1.2.3")  # flow_version
def my_flow():
    ...

# Deployment version is separate and optional
my_flow.deploy(
    name="prod",
    version="2026-03-12-a",  # deployment_version
    work_pool_name="prod-pool"
)

Where to read more - Flow decorator/API (version param): https://github.com/PrefectHQ/prefect/blob/main/src/prefect/flows.py - Runtime access to run fields: https://github.com/PrefectHQ/prefect/blob/main/src/prefect/runtime/flow_run.py - Deployment runner (version defaulting logic): https://github.com/PrefectHQ/prefect/blob/main/src/prefect/deployments/runner.py - Deployments overview (docs): https://docs.prefect.io/latest/deploy/ (see versioning/updates for Prefect Cloud)