Environment:PrefectHQ Prefect Python Runtime Environment

Knowledge Sources	PrefectHQ/prefect pyproject.toml
Domains	Infrastructure, Runtime
Last Updated	2026-02-09 22:00 GMT

Overview

Python 3.10–3.14 runtime environment with version-conditional dependencies: pendulum for Python <3.13 and whenever for Python >=3.13.

Description

Prefect requires Python 3.10 or later (up to 3.14) as its core runtime. The codebase contains significant version-conditional logic, particularly around datetime handling. Python 3.13+ uses the standard library's `zoneinfo` and `whenever` package instead of `pendulum`, which is used on Python <3.13. Python 3.14+ drops support for Pydantic v1 schema generation entirely. The full dependency set includes ~45 direct packages spanning HTTP clients, async frameworks, database adapters, and serialization libraries.

Usage

This environment is required for all Prefect workflows. Every flow, task, deployment, and server instance requires this Python runtime. The version-conditional datetime handling means that behavior may differ subtly between Python 3.12 and 3.13+ environments.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows (WSL2 recommended)	Platform-specific code paths exist for signal handling and process management
Python	>= 3.10, < 3.15	3.10, 3.11, 3.12, 3.13, 3.14 officially supported
Disk	500MB+	For package installation and local SQLite database

Dependencies

System Packages

`python` >= 3.10, < 3.15
`git` (for version control integration and deployment sources)

Python Packages (Core Server)

`aiosqlite` >= 0.17.0, < 1.0.0
`alembic` >= 1.7.5, < 2.0.0
`apprise` >= 1.1.0, < 2.0.0
`asyncpg` >= 0.23, < 1.0.0
`click` >= 8.0, < 9
`cryptography` >= 36.0.1
`docker` >= 4.0, < 8.0
`sqlalchemy[asyncio]` >= 2.0, < 3.0.0
`typer` >= 0.16.0, < 0.22.0

Python Packages (Core Client)

`anyio` >= 4.4.0, < 5.0.0
`cloudpickle` >= 2.0, < 4.0
`fastapi` >= 0.111.0, < 1.0.0
`httpx[http2]` >= 0.23
`orjson` >= 3.7, < 4.0
`packaging` >= 21.3, < 25.1
`pydantic` >= 2.10.1, < 3.0.0 (excluding 2.11.0–2.11.4)
`pydantic_settings` > 2.2.1, < 3.0.0 (excluding 2.9.0)
`rich` >= 11.0, < 15.0
`websockets` >= 15.0.1, < 17.0
`typing_extensions` >= 4.10.0, < 5.0.0

Version-Conditional Packages

`pendulum` >= 3.0.0, < 4 (Python < 3.13 only)
`whenever` >= 0.7.3, < 0.10.0 (Python >= 3.13 only)
`ruamel.yaml.clib` >= 0.2.8 (CPython only)

Credentials

No credentials are required for the base runtime environment. See Environment:PrefectHQ_Prefect_AI_Integration_Credentials for API key requirements.

Quick Install

# Install Prefect (all core dependencies included)
pip install prefect

# With optional integration extras
pip install "prefect[aws,docker,kubernetes]"

# For dbt integration
pip install "prefect[dbt]"

Code Evidence

Python version-conditional datetime handling from `src/prefect/types/_datetime.py:14-33`:

if sys.version_info >= (3, 13):
    DateTime: TypeAlias = datetime.datetime
    Date: TypeAlias = datetime.date
    Duration: TypeAlias = datetime.timedelta
else:
    import pendulum
    import pendulum.tz
    from pydantic_extra_types.pendulum_dt import (
        Date as PydanticDate,
        DateTime as PydanticDateTime,
        Duration as PydanticDuration,
    )

Pydantic v1 removal for Python 3.14+ from `src/prefect/_internal/pydantic/v1_schema.py:15`:

if sys.version_info >= (3, 14):
    # Pydantic v1 is not supported on Python 3.14+

Python version constraint from `pyproject.toml:10`:

requires-python = ">=3.10,<3.15"

Common Errors

Error Message	Cause	Solution
`ModuleNotFoundError: No module named 'pendulum'`	Running Python 3.13+ where pendulum is not installed	Expected on Python 3.13+; Prefect uses `whenever` instead. Ensure `whenever` is installed.
`ImportError: pydantic v1 schema generation not supported`	Running Python 3.14+ with code that uses Pydantic v1 patterns	Migrate to Pydantic v2 schema generation. Pydantic v1 compatibility is removed on Python 3.14+.
`TypeError: ... requires Python >=3.10`	Python version too old	Upgrade to Python 3.10 or later.

Compatibility Notes

Python 3.13+: DateTime handling switches from `pendulum` to standard library `datetime` with `whenever`. Schedule parsing and timezone behavior may differ.
Python 3.14+: Pydantic v1 schema generation is fully removed. All models must use Pydantic v2.
CPython vs PyPy: `ruamel.yaml.clib` is only installed on CPython (`platform_python_implementation == 'CPython'`).
Windows: Subprocess creation requires special `creationflags`; signal handling (SIGTERM/SIGKILL) differs from POSIX systems. WSL2 is recommended.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment