Prefect Cheat Sheet

1Install & first flow@flow

pip install prefect★
Python 3.9+. Bundles the CLI, an embedded SQLite-backed server, and the UI.
from prefect import flow @flow def pipeline(name: str): print(f"hello {name}") if __name__ == "__main__": pipeline("world")★
A flow is any function wrapped in @flow. Call it like normal Python — Prefect creates a tracked flow run with logs, timing, and state.
@flow(name="etl", log_prints=True, retries=2) def etl(): ...★
Flow options: name, retries/retry_delay_seconds, log_prints (capture print), timeout_seconds, description.
prefect server start # local UI at http://127.0.0.1:4200
Run the self-hosted server + UI to see runs. Or connect to Prefect Cloud (card 11).

2Tasks & futures@task

from prefect import flow, task @task def extract(url): return requests.get(url).json() @flow def etl(): data = extract("https://api/x")★
Tasks are the retriable, cacheable units. Call them from inside a flow — each call is a tracked task run.
fut = extract.submit(url) # run concurrently, returns a future result = fut.result()★
.submit() runs a task in the flow's task runner (concurrent by default) and returns a future; .result() blocks for the value.
results = extract.map([u1, u2, u3]) # fan out over an iterable★
.map() spawns one task run per item — parallel fan-out without writing a loop.
# calling a @task outside a @flow just runs the functionnote
Tasks orchestrate only within a flow. Outside one they execute as plain functions (no tracking/retries).

3Retries, caching & loggingresilience

@task(retries=3, retry_delay_seconds=[1, 10, 60])★
Automatic retries with fixed or backoff delays. retry_condition_fn to retry only on certain failures.
from prefect.cache_policies import INPUTS, TASK_SOURCE @task(cache_policy=INPUTS + TASK_SOURCE, cache_expiration=timedelta(hours=1))★
Caching: skip re-running a task when its inputs (and code) are unchanged — keyed by a cache_policy. Big win for expensive/idempotent steps.
from prefect import get_run_logger logger = get_run_logger(); logger.info("processed %d rows", n)★
Use the run logger so messages show in the UI attached to the run (or set log_prints=True on the flow).
@task(tags=["db"], timeout_seconds=30)
Tags drive concurrency limits (card 5); timeouts fail long-hanging tasks.

4States & resultsobservability

# states: Scheduled -> Pending -> Running -> Completed / Failed / Crashed★
Runs move through states you see in the UI. Retrying, Cancelled, and Paused are states too.
state = etl(return_state=True) if state.is_failed(): ... state.result()★
return_state=True gives the State object instead of the return value — inspect success/failure and pull the result.
@task(persist_result=True, result_storage="s3-bucket/prefect")
Results can be persisted to storage (S3/GCS/local) so downstream runs & caching can reuse them.
from prefect.transactions import transaction with transaction(): write_a(); write_b() # rolls back on failurev3
Prefect 3 transactions group steps with rollback hooks for atomic, idempotent pipelines.

5Concurrency & subflowsparallel & compose

from prefect.task_runners import ThreadPoolTaskRunner @flow(task_runner=ThreadPoolTaskRunner(max_workers=8))★
Task runners drive concurrency. Threaded by default; DaskTaskRunner/RayTaskRunner (extra packages) distribute across a cluster.
@flow def parent(): child_flow() # a flow called inside a flow = a subflow★
Call a flow from a flow to compose pipelines — the subflow gets its own tracked run, nested under the parent.
prefect concurrency-limit create db 5
Global concurrency limits by tag (e.g. at most 5 tasks tagged db running cluster-wide) — protect shared resources.
async def etl(): ... # @flow / @task support async natively
Async flows/tasks work out of the box — await your tasks for I/O-bound concurrency.

6serve() & schedulesthe easy path

etl.serve(name="nightly", cron="0 2 * * *")★
flow.serve() creates a deployment and starts a long-running process that executes scheduled/triggered runs — the fastest way to productionize on one machine.
from prefect import serve serve(etl.to_deployment("a", cron="@daily"), report.to_deployment("b", interval=3600))
Serve several deployments from one process. Schedules: cron, interval (seconds), or RRule.
etl.serve(..., parameters={"env": "prod"})
Bake default parameters; override per run from the UI/CLI/API. Parameters are validated (Pydantic).

7Deploymentsremote runs

etl.deploy(name="prod", work_pool_name="k8s", image="myrepo/etl:latest", cron="@hourly")★
A deployment is the server-side record of how/when/where a flow runs. .deploy() builds & pushes an image and registers it to a work pool.
# prefect.yaml — declarative deployments (built with `prefect deploy`) deployments: - name: prod entrypoint: flows/etl.py:etl work_pool: {name: k8s} schedules: [{cron: "@hourly"}]★
prefect.yaml is the version-controlled, multi-deployment config with build/push/pull steps. Deploy with prefect deploy.
prefect deployment run 'etl/prod' # trigger an ad-hoc run
Trigger from the CLI/UI/API. Runs land in the deployment's work pool.

8Work pools & workersinfra per run

prefect work-pool create k8s --type kubernetes★
A work pool defines the infrastructure type & defaults for runs: process, docker, kubernetes, ECS, Cloud Run, and more.
prefect worker start --pool k8s★
A worker polls its pool and provisions infra for each scheduled run (spins up a pod/container, runs the flow, tears it down). One worker per pool.
# push work pools (serverless) need no worker at all
Push pools (e.g. Cloud Run/ECS/Modal push) submit runs directly — no long-running worker to babysit.
# deployment scheduled but nothing runs? no worker on the poolgotcha
A pull work pool needs a running worker (or the process running serve()). No worker = runs sit Scheduled forever.

9Blocks & variablesconfig & secrets

from prefect.blocks.system import Secret Secret(value="...").save("api-key") key = Secret.load("api-key").get()★
Blocks are reusable, typed config objects (credentials, storage, notifications) stored on the server. Integration packages add S3/GCS/Snowflake/Slack blocks.
from prefect.variables import Variable Variable.set("batch_size", 500) · Variable.get("batch_size")
Variables hold small, non-secret config shared across flows/deployments.
from prefect_aws import S3Bucket S3Bucket.load("my-bucket").upload_from_path(...)
Integration blocks wrap cloud services with saved credentials — load by name inside tasks.

10Automations & artifactsreact & report

# Automations (UI): on flow-run Failed -> send Slack / email★
Automations fire actions on events (run failed, deployment stuck, custom events) — alerting, retries, cancellations, webhooks.
from prefect.artifacts import create_table_artifact, create_markdown_artifact create_markdown_artifact("## Report\n...", key="summary")★
Artifacts publish tables, markdown, links, and progress to a run for humans — surface results in the UI.
from prefect.events import emit_event emit_event("data.arrived", resource={"prefect.resource.id":"file/1"})
Emit custom events to trigger event-driven deployments (webhook-style pipelines).

11CLI & serveroperate it

prefect cloud login # or: prefect config set PREFECT_API_URL=...★
Point the CLI/SDK at Prefect Cloud (hosted, with RBAC, events, SLAs) or your self-hosted server.
prefect flow-run ls · prefect deployment ls · prefect work-pool ls
Inspect runs, deployments, pools from the terminal.
prefect server start · prefect config view
Run the local server + UI; view resolved settings/profiles.

12Ecosystemwhere it fits

# Prefect = Python-first, imperative; Airflow = DAG-centric; Dagster = asset-centric★
Prefect's pitch is minimal ceremony — add decorators to real code. Airflow is the incumbent scheduler; Dagster models data assets. All three orchestrate; pick by mental model.
pip install prefect-aws prefect-gcp prefect-dbt prefect-snowflake
Integration collections add blocks & tasks for clouds, warehouses, dbt, Kubernetes, Docker, etc.
# pairs with dbt, dlt, pandas/Polars, Dask/Ray for compute
Prefect orchestrates; it doesn't replace your transform/compute tools — it schedules & observes them.

Prefect cheat sheet

Outline

Flows & tasks

Control & state

Deploying

Config & ecosystem

Flows & Tasks

Control & State

Deploying

Config & Ecosystem

Worth memorizing