prefect

library3.8.4pypypi✓ verified 27d ago

Prefect is an open-source workflow orchestration and management system that allows users to build, run, and monitor data pipelines. It provides a robust framework for defining workflows as Python code, complete with task dependencies, retries, caching, and state management. The current stable version is 3.6.25, with frequent nightly development builds and stable releases typically every few weeks.

workflow data devops

pip install prefect

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PREFECT

prefect

workflowpythonv3.8.4

Install

21.4s avg

Import

5127ms

Disk

249MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.8.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 5.268s · 254.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 21.4s · import 4.986s · 255MB

249MB installed

● package 249MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

flow

✓ from prefect import flow

task

✓ from prefect import task

serve

✓ from prefect import serve

Deployment

✓ from prefect.deployments import Deployment

✗ from prefect import Deployment

Deployment class is located in `prefect.deployments` since Prefect 2.

This quickstart defines a simple task and a flow that uses it. It then demonstrates how to `serve` the flow, which will start a local Prefect API server and agent, and register the flow as a deployment. This allows you to observe flow runs and their states in the Pref Prefect UI (http://localhost:4200). For connecting to Prefect Cloud, set `PREFECT_API_URL` and `PREFECT_API_KEY` environment variables.

import os from prefect import flow, task, serve @task def greet_task(name: str): """A simple task that prints a greeting.""" print(f"Hello from task, {name}!") return f"Task processed: {name}" @flow(log_prints=True) def my_orchestrated_flow(name: str = "World"): """A flow that uses the greet_task and prints its result.""" print(f"Flow starting for {name}...") task_result = greet_task(name) print(f"Flow received result: {task_result}") return f"Flow completed for {name}" if __name__ == "__main__": # To connect to Prefect Cloud, set these environment variables: # os.environ['PREFECT_API_URL'] = os.environ.get('PREFECT_API_URL', 'https://api.prefect.cloud/api/accounts/.../workspaces/...') # os.environ['PREFECT_API_KEY'] = os.environ.get('PREFECT_API_KEY', 'pf_...') # To run a flow and see it in the UI, it must be 'served' or deployed. # This starts a local Prefect API server and an agent, then registers the deployment. # Access the UI at http://localhost:4200 print("Serving 'my_orchestrated_flow' locally. Open http://localhost:4200 in your browser.") serve(my_orchestrated_flow.to_deployment(name="my-first-deployment", interval=10)) # To simply run a flow locally without orchestration (not recommended for production): # my_orchestrated_flow("Local User")

prefect --version

Debug

Known issues

breakingPrefect 2 (current major version) is a complete rewrite and is NOT backward compatible with Prefect 1. Code written for Prefect 1 will not run on Prefect 2 without significant modification. Key concepts like 'projects' were replaced by 'deployments', and the API changed entirely.

fix

Review the Prefect 2 migration guide and rewrite existing Prefect 1 flows to conform to the new API and concepts. There is no automated upgrade path.

affects: All Prefect 2.x.x versions when migrating from Prefect 1.x.x

gotchaRunning `my_flow()` executes the flow locally as a plain Python function. To leverage Prefect's orchestration features (retries, scheduling, state tracking, UI visibility), flows must be 'deployed'. This is typically done via `flow.to_deployment()` combined with `serve()` or using the `prefect deploy` CLI.

fix

Always use `flow.to_deployment()` and then either `serve()` for local development/testing or `prefect deploy` for production environments to register your flow with the Prefect API and enable orchestration.

affects: All Prefect 2.x.x versions

gotchaThe Prefect UI/API server does not automatically start with `pip install prefect`. For local orchestration and UI access, you must either run `prefect server start` or use `prefect serve()` as demonstrated in the quickstart. If connecting to Prefect Cloud, ensure `PREFECT_API_URL` and `PREFECT_API_KEY` are correctly configured.

fix

For local development, use `prefect serve()` to start a temporary server and agent, or run `prefect server start` in a separate terminal. For Prefect Cloud, set the necessary environment variables (`PREFECT_API_URL`, `PREFECT_API_KEY`).

affects: All Prefect 2.x.x versions

gotchaWhen modifying a flow's code, you must re-deploy or re-serve the flow for the changes to take effect in your Prefect deployments. Simply saving the Python file is not enough; the updated definition needs to be registered with the Prefect API.

fix

After code changes, re-run your `serve()` script or use the `prefect deploy` CLI command to update the deployment definition.

affects: All Prefect 2.x.x versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'prefect'

The Python interpreter cannot find the 'prefect' library or a custom module required by your flow, often due to an inactive virtual environment, incorrect Python environment, or missing dependencies in the flow's execution environment (e.g., Docker image, agent environment).

fix

Ensure Prefect and all custom flow dependencies are installed in the Python environment where the flow is executed. If running locally, activate your virtual environment. For deployments, verify the Docker image or execution environment includes all necessary packages and that the Python path is correctly configured for custom modules. Example for installation: `pip install prefect`.

Flow run enters Crashed state / no heartbeat detected

The process running the flow or task terminated unexpectedly, lost communication with the Prefect server/Cloud, or the underlying infrastructure failed to provision. Common reasons include out-of-memory (OOM) errors, CPU/GIL contention, long-running blocking calls, network issues, or aggressive infrastructure timeouts.

fix

Check worker/container logs for OOM or other termination signals. Increase resources (memory, CPU) for the execution environment. For long-running tasks, consider breaking them down, utilizing Prefect's concurrency features, or adjusting the `PREFECT_RUNNER_HEARTBEAT_FREQUENCY` environment variable. Ensure stable network connectivity to the Prefect API.

httpx.ConnectError: All connection attempts failed / 401 Unauthorized

The Prefect client or worker cannot connect to the Prefect API endpoint (Prefect Cloud or self-hosted server) due to an incorrect `PREFECT_API_URL`, an invalid or expired `PREFECT_API_KEY`, network issues, or proxy configuration problems.

fix

Verify `PREFECT_API_URL` and `PREFECT_API_KEY` environment variables or profile settings using `prefect config view`. Ensure the API key is valid and has the necessary permissions. Check network connectivity, firewall rules, and proxy settings (e.g., `HTTPS_PROXY`, `SSL_CERT_FILE`) to allow communication with the Prefect API. If self-hosting, ensure the Prefect server is running and accessible.

AttributeError: 'NoneType' object has no attribute 'name' (during prefect deploy)

This error occurs when the `prefect deploy` command attempts to access the 'name' attribute of a flow object, but the flow object itself is 'None'. This typically happens if the Prefect CLI fails to load the flow from the specified entrypoint (e.g., due to a `FileNotFoundError` or issues during script evaluation) before registration.

fix

Ensure the deployment's `entrypoint` in your `prefect.yaml` correctly points to an existing Python file and a valid Prefect flow function within it. Verify that the file exists and is accessible from the environment where `prefect deploy` is run. Check that any dependencies required for loading the flow are present in that environment. For example, if your flow is `my_module.py:my_flow`, ensure `my_module.py` exists and `my_flow` is a `@flow` decorated function.

Upgrade

Version history

3.8.4latest on PyPI · released Aug 25, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/PrefectHQ/prefect ↗

packagehttps://pypi.org/project/prefect/ ↗

homepagehttps://www.prefect.io ↗

docshttps://docs.prefect.io ↗

changeloghttps://github.com/PrefectHQ/prefect/releases ↗