Deployments are server-side representations of flows. They store the crucial metadata for remote orchestration including when, where, and how a workflow should run. Attributes of a deployment include:
  • Flow entrypoint: path to your flow function
  • Schedule or Trigger: optional schedule or triggering rules for this deployment
  • Tags: optional text labels for organizing deployments
Some of the most common reasons to use an orchestration tool like Prefect are for scheduling and event-based triggering. As opposed to manually triggering and managing flow runs, deploying a flow exposes an API and UI that allow you to:
  • trigger new runs, cancel active runs, pause scheduled runs, customize parameters, and more
  • remotely configure schedules and automation rules for your deployments
  • dynamically provision infrastructure using workers
Connect to Prefect Cloud or a self-hosted Prefect server instanceSome features in this tutorial, such as scheduling, require you to connect to a Prefect server. If using a self-hosted setup, run prefect server start to run both the webserver and UI. If using Prefect Cloud, make sure you have successfully authenticated your local environment.

​
Create a deployment

Here’s an example of creating a deployment by calling a single method on the flow object: flow.serve.
repo_info.py
import httpx
from prefect import flow


@flow(log_prints=True)
def get_repo_info(repo_name: str = "PrefectHQ/prefect"):
    url = f"https://api.github.com/repos/{repo_name}"
    response = httpx.get(url)
    response.raise_for_status()
    repo = response.json()
    print(f"{repo_name} repository statistics 🤓:")
    print(f"Stars 🌠 : {repo['stargazers_count']}")
    print(f"Forks 🍴 : {repo['forks_count']}")


if __name__ == "__main__":
    get_repo_info.serve(name="my-first-deployment")
Running this script will:
  • create a deployment called my-first-deployment for your flow in the Prefect API
  • continue running to listen for flow runs for this deployment; when a run is found, it
    asynchronously executes within a subprocess
You must define deployments in static filesYou can define and run flows interactively, within REPLs or Notebooks. However, deployments require that your flow definition exist in a known file.
Because this deployment doesn’t have a schedule or triggering automation, you must use the UI or API to create runs for it. Use the CLI (in a separate terminal window) to create a run for this deployment: 
prefect deployment run 'get-repo-info/my-first-deployment'
In your terminal or UI, you should see the newly created run execute successfully.

​
Additional options

The serve method on flows exposes many options for the deployment. For more information, see Serve a flow Here’s how to use some of those options:
  • cron: a keyword that allows you to set a cron string schedule for the deployment; see schedules for more advanced scheduling options
  • tags: a keyword that allows you to tag this deployment and its runs for bookkeeping and filtering purposes
  • description: a keyword that allows you to document what this deployment does; by default the description is set from the docstring of the flow function (if documented)
  • version: a keyword that allows you to track changes to your deployment; uses a hash of the file containing the flow by default; popular options include semver tags or git commit hashes
Next, add these options to your deployment: 
if __name__ == "__main__":
    get_repo_info.serve(
        name="my-first-deployment",
        cron="* * * * *",
        tags=["testing", "tutorial"],
        description="Given a GitHub repository, logs repository statistics for that repo.",
        version="tutorial/deployments",
    )
When you rerun this script, you will find an updated deployment in the UI that is actively scheduling work.
Stop the script in the CLI using CTRL+C and your schedule automatically pauses.
.serve is a long-running processTo execute remotely triggered or scheduled runs, your script with flow.serve must be actively running.

​
Run multiple deployments at once

This method is useful for creating deployments for single flows. For two or more flows, you must provide a few additional method calls and imports:
multi_flow_deployment.py
import time
from prefect import flow, serve


@flow
def slow_flow(sleep: int = 60):
    "Sleepy flow - sleeps the provided amount of time (in seconds)."
    time.sleep(sleep)


@flow
def fast_flow():
    "Fastest flow this side of the Mississippi."
    return


if __name__ == "__main__":
    slow_deploy = slow_flow.to_deployment(name="sleeper", interval=45)
    fast_deploy = fast_flow.to_deployment(name="fast")
    serve(slow_deploy, fast_deploy)
A few things to note:
  • the flow.to_deployment interface exposes the exact same options as flow.serve; this method produces a deployment object
  • the deployments are only registered with the API once serve(...) is called
  • when serving multiple deployments, the only requirement is that they share a Python environment; they can be executed and scheduled independently of each other
A few optional steps for exploration include:
  • pause and unpause the schedule for the “sleeper” deployment
  • use the UI to submit ad-hoc runs for the “sleeper” deployment with different values for sleep
  • cancel an active run for the “sleeper” deployment from the UI
Hybrid execution optionPrefect’s deployment interface allows you to choose a hybrid execution model. Whether you use Prefect Cloud or host a Prefect server instance, you can run workflows in the environments best suited to their execution. This model enables efficient use of your infrastructure resources while maintaining the privacy of your code and data. There is no ingress required. Read more about our hybrid model.

​
Deployment schema

Here’s the complete schema that defines a deployment: 
class Deployment:
    """
    Structure of the schema defining a deployment
    """

    # required defining data
    name: str 
    flow_id: UUID
    entrypoint: str
    path: Optional[str] = None

    # workflow scheduling and parametrization
    parameters: Optional[Dict[str, Any]] = None
    parameter_openapi_schema: Optional[Dict[str, Any]] = None
    schedules: list[Schedule] = None
    paused: bool = False
    trigger: Trigger = None

    # metadata for bookkeeping
    version: Optional[str] = None
    description: Optional[str] = None
    tags: Optional[list] = None

    # worker-specific fields
    work_pool_name: Optional[str] = None
    work_queue_name: Optional[str] = None
    infra_overrides: Optional[Dict[str, Any]] = None
    pull_steps: Optional[Dict[str, Any]] = None
All methods for creating Prefect deployments are interfaces for populating this schema. The following sections explain each component in more detail.

​
Required data

Deployments universally require a name and a reference to an underlying Flow. The deployment name is not required to be unique across all deployments, but is required to be unique for a given flow ID. This means you will often see references to the deployment’s unique identifying name {FLOW_NAME}/{DEPLOYMENT_NAME}. For example, triggering a run of a deployment from the Prefect CLI can be done with: 
prefect deployment run my-first-flow/my-first-deployment
The other two fields are:
  • path: think of the path as the runtime working directory for the flow. For example, if a deployment references a workflow defined within a Docker image, the path is the
    absolute path to the parent directory where that workflow will run anytime the deployment is triggered. This interpretation is more subtle in the case of flows defined in remote filesystems.
  • entrypoint: the entrypoint of a deployment is a relative reference to a function decorated as a flow that exists on some filesystem. It is always specified relative to the path. Entrypoints use Python’s standard path-to-object syntax (for example, path/to/file.py:function_name or simply path:object).
The entrypoint must reference the same flow as the flow ID. Prefect requires that deployments reference flows defined within Python files. Flows defined within interactive REPLs or notebooks cannot currently be deployed as such. They are still valid flows that will be monitored by the API and observable in the UI whenever they are run, but Prefect cannot trigger them.
Deployments do not contain code definitionsDeployment metadata references code that exists in potentially diverse locations within your environment. This separation means that your flow code stays within your storage and execution infrastructure, and never lives on the Prefect server or database.This is key to the Prefect hybrid model: there’s a boundary between your proprietary assets, such as your flow code, and the Prefect backend (including Prefect Cloud).

​
Scheduling and parametrization

One of the primary motivations for creating deployments of flows is to remotely schedule and trigger them. Just as you can call flows as functions with different input values, deployments can be triggered or scheduled with different values through parameters. These are the fields to capture the required metadata for those actions:
  • schedules: a list of schedule objects. Most of the convenient interfaces for creating deployments allow users to avoid creating this object themselves. For example, when updating a deployment schedule in the UI basic information such as a cron string or interval is all that’s required.
  • trigger (Cloud-only): triggers allow you to define event-based rules for running a deployment. For more information see Automations.
  • parameter_openapi_schema: an OpenAPI compatible schema that defines the types and defaults for the flow’s parameters. This is used by the UI and the backend to expose options for creating manual runs as well as type validation.
  • parameters: default values of flow parameters that this deployment will pass on each run. These can be overwritten through a trigger or when manually creating a custom run.
  • enforce_parameter_schema: a boolean flag that determines whether the API should validate the parameters passed to a flow run against the schema defined by parameter_openapi_schema.
Scheduling is asynchronous and decoupledPausing a schedule, updating your deployment, and other actions reset your auto-scheduled runs.

​
Run a deployed flow from within Python flow code

Prefect provides a run_deployment function to schedule the run of an existing deployment when your Python code executes. 
from prefect.deployments import run_deployment

def main():
    run_deployment(name="my_flow_name/my_deployment_name")
Run a deployment without blockingBy default, run_deployment blocks until the scheduled flow run finishes executing. Pass timeout=0 to return immediately and not block.
If you call run_deployment from within a flow or task, the scheduled flow run is linked to the calling flow run (or the calling task’s flow run) as a subflow run by default. Subflow runs have different behavior than regular flow runs. For example, you can’t suspend a subflow run independently of its parent flow. To not link the scheduled flow run to the calling flow or task run, pass as_subflow=False to disable it: 
from prefect import flow
from prefect.deployments import run_deployment


@flow
def my_flow():
    # The scheduled flow run will not be linked to this flow as a subflow.
    run_deployment(name="my_other_flow/my_deployment_name", as_subflow=False)
The return value of run_deployment is a FlowRun object containing metadata about the scheduled run. Use this object to retrieve information about the run after calling run_deployment: 
from prefect import get_client
from prefect.deployments import run_deployment

def main():
    flow_run = run_deployment(name="my_flow_name/my_deployment_name")
    flow_run_id = flow_run.id

    # If you save the flow run's ID, you can use it later to retrieve
    # flow run metadata again, e.g. to check if it's completed.
    async with get_client() as client:
        flow_run = client.read_flow_run(flow_run_id)
        print(f"Current state of the flow run: {flow_run.state}")
Using the Prefect clientFor more information on using the Prefect client to interact with Prefect’s REST API, see Interact with the API.

​
Versioning and bookkeeping

Here is important information on the versions, descriptions, and tags fields:
  • version: versions are always set by the client and can be any arbitrary string. We recommend tightly coupling this field on your deployments to your software development lifecycle. For example if you leverage git to manage code changes, use either a tag or commit hash in this field. If you don’t set a value for the version, Prefect will compute a hash.
  • description: provide reference material such as intended use and parameter documentation. Markdown is accepted. The docstring of your flow function is the default value.
  • tags: group related work together across a diverse set of objects. Tags set on a deployment are inherited by that deployment’s flow runs. Filter, customize views, and searching by tag.
Everything has a versionDeployments have a version attached; and flows and tasks also have versions set through their respective decorators. These versions are sent to the API anytime the flow or task runs, allowing you to audit changes.

​
Workers and work pools

Workers and work pools are an advanced deployment pattern that allow you to dynamically provision infrastructure for each flow run. The work pool job template interface allows users to create and govern opinionated interfaces to their workflow infrastructure. To do this, a deployment using workers needs the following fields:
  • work_pool_name: the name of the work pool this deployment is associated with. Work pool types mirror infrastructure types, which means this field impacts the options available for the other fields.
  • work_queue_name: if you are using work queues to either manage priority or concurrency, you can associate a deployment with a specific queue within a work pool using this field.
  • infra_overrides: often called job_variables within various interfaces, this field allows deployment authors to customize whatever infrastructure options have been exposed on this work pool. This field is often used for Docker image names, Kubernetes annotations and limits, and environment variables.
  • pull_steps: a JSON description of steps that retrieves flow code or configuration, and prepares the runtime environment for workflow execution.
Pull steps allow users to highly decouple their workflow architecture. For example, a common use of pull steps is to dynamically pull code from remote filesystems such as GitHub with each run of their deployment.

​
Serving flows on long-lived infrastructure

When you have several flows running regularly, the serve method of the Flow object or the serve utility is a great option for managing multiple flows simultaneously. Once you have authored your flow and decided on its deployment settings, run this long-running process in a location of your choosing. The process stays in communication with the Prefect API, monitoring for work and submitting each run within an individual subprocess. Because runs are submitted to subprocesses, any external infrastructure configuration must be set up beforehand and kept associated with this process. This approach has these benefits:
  • Users are in complete control of their infrastructure, and anywhere the “serve” Python process can run is a suitable deployment environment.
  • It is simple to reason about.
  • Creating deployments requires a minimal set of decisions.
  • Iteration speed is fast.

​
Dynamically provisioning infrastructure with work pools

Consider running flows on dynamically provisioned infrastructure with work pools under these circumstances:
  • Flows that have expensive infrastructure due to the long-running process.
  • Flows with heterogeneous infrastructure needs across runs.
  • Large volumes of deployments.
  • If your internal team structure requires that deployment authors be members of a different team than the team managing infrastructure.
Work pools allow Prefect to exercise greater control of the infrastructure on which flows run. Options for serverless work pools allow you to scale to zero when workflows aren’t running. Prefect even provides you with the ability to provision cloud infrastructure via a single CLI command, if you use a Prefect Cloud push work pool option. With work pools:
  • You can configure and monitor infrastructure configuration within the Prefect UI.
  • Infrastructure is ephemeral and dynamically provisioned.
  • Prefect is more infrastructure-aware and collects more event data from your infrastructure by default.
  • Highly decoupled setups are possible.
You don’t have to commit to one approachYou can mix and match approaches based on the needs of each flow. You can also change the deployment approach for a particular flow as its needs evolve. For example, you might use workers for your expensive machine learning pipelines, but use the serve mechanics for smaller, more frequent file-processing pipelines.