Implementation:PrefectHQ Prefect Client Pyproject Configuration

Knowledge Sources	PrefectHQ_Prefect Prefect Docs PyPA Packaging
Domains	Packaging, Configuration, Build_System
Last Updated	2026-02-09 22:00 GMT

Overview

Package configuration for the lightweight `prefect-client` PyPI distribution, defining its reduced client-only dependency set and build settings.

Description

The client/pyproject.toml defines the `prefect-client` package, a lightweight alternative to the full `prefect` package intended for environments that only need client-side functionality (e.g., submitting flow runs, reading results) without the server components. It uses hatchling as the build backend with versioningit for dynamic Git-based versioning. Compared to the full `prefect` package, it excludes server-specific dependencies like SQLAlchemy, Alembic, aiosqlite, asyncpg, and the CLI tools. The client package targets Python 3.10-3.14 and includes the `notifications` optional extra.

Usage

Install `prefect-client` instead of `prefect` when deploying to environments where you only need to interact with a remote Prefect server or Prefect Cloud, without running the server locally. This significantly reduces the installation footprint.

Code Reference

Source Location

• Repository: PrefectHQ_Prefect
• File: client/pyproject.toml
• Lines: 1-101

Signature

[build-system]
requires = ["hatchling", "versioningit"]
build-backend = "hatchling.build"

[project]
name = "prefect-client"
dynamic = ["version"]
description = "Workflow orchestration and management."
requires-python = ">=3.10,<3.15"
license = { text = "Apache-2.0" }

dependencies = [
    # Client dependencies only (no SQLAlchemy, Alembic, etc.)
    "httpx[http2]>=0.23,!=0.23.2",
    "pydantic>=2.10.1,<3.0.0",
    "anyio>=4.4.0,<5.0.0",
    "fastapi>=0.111.0,<1.0.0",
    # ... ~40 client-only dependencies
]

[project.optional-dependencies]
notifications = ["apprise>=1.1.0, <2.0.0"]

[tool.hatch.build.targets.wheel]
packages = ["src/prefect"]

Import

# Install the lightweight client package
pip install prefect-client

# Use the same prefect API after installation
python -c "from prefect import flow; print('prefect-client works!')"

I/O Contract

Inputs

Name	Type	Required	Description
build-system	table	Yes	Build backend configuration (hatchling + versioningit)
project.name	string	Yes	Package name ("prefect-client")
project.dependencies	array	Yes	Client-only runtime dependencies (~40 packages)
project.optional-dependencies	table	No	Extra groups (notifications)

Outputs

Name	Type	Description
prefect-client package	wheel/sdist	Lightweight Python distribution on PyPI
prefect module	Python package	Same `prefect` namespace, server components excluded at build time

Usage Examples

Installing prefect-client

# Install the lightweight client
pip install prefect-client

# Install with notification support
pip install prefect-client[notifications]

Using prefect-client for Remote Submissions

from prefect.client import get_client

async def submit_flow_run():
    async with get_client() as client:
        # Create a flow run on a remote Prefect server
        flow_run = await client.create_flow_run_from_deployment(
            deployment_id="my-deployment-id",
            parameters={"key": "value"},
        )
        print(f"Created flow run: {flow_run.id}")

Related Pages

• Environment:PrefectHQ_Prefect_Python_Runtime_Environment