Install & Compatibility
Where this runs
tested against v3.7.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 4.618s · 94.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 16.2s · import 4.462s · 95MB
158MB installed
● package 158MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run_deployment
✓ from prefect.deployments import run_deployment
Used to remotely trigger a deployed flow on a Prefect server or Cloud.
emit_event
✓ from prefect.events import emit_event
For emitting custom events that can be captured by Prefect automations.
get_client
✓ from prefect.client.orchestration import get_client
✗ from prefect.client import PrefectClient
`get_client` is the recommended asynchronous context manager for API interaction; direct `PrefectClient` instantiation is less common and often requires manual lifecycle management.
This quickstart demonstrates how to use `prefect-client` to interact with a remote Prefect server or Prefect Cloud. It shows how to trigger a deployed flow and how to query the API for existing deployments. Ensure the `PREFECT_API_URL` and `PREFECT_API_KEY` environment variables are set for successful connection to your Prefect instance.
import os
import asyncio
from prefect.deployments import run_deployment
from prefect.client.orchestration import get_client
# Ensure API URL and Key are set as environment variables for remote connection
os.environ['PREFECT_API_URL'] = os.environ.get('PREFECT_API_URL', 'http://localhost:4200/api')
os.environ['PREFECT_API_KEY'] = os.environ.get('PREFECT_API_KEY', 'your_api_key_if_needed')
async def interact_with_prefect_api():
print(f"Connecting to Prefect API at: {os.environ['PREFECT_API_URL']}")
async with get_client() as client:
# Example 1: Remotely trigger a deployment
try:
flow_run = await run_deployment(
name="my-flow/my-deployment",
parameters={"message": "Hello from prefect-client!"},
timeout=0 # Do not wait for the flow run to complete
)
print(f"Triggered flow run: {flow_run.name} (ID: {flow_run.id})")
except Exception as e:
print(f"Could not trigger deployment: {e}. Ensure 'my-flow/my-deployment' exists and is accessible.")
# Example 2: Read some information from the API
try:
deployments = await client.read_deployments(limit=5)
print(f"\nFound {len(deployments)} deployments:")
for dep in deployments:
print(f" - {dep.name} (ID: {dep.id})")
except Exception as e:
print(f"Could not read deployments: {e}. Check API URL/Key and server status.")
if __name__ == "__main__":
# Note: If connecting to Prefect Cloud, ensure PREFECT_API_KEY is set
# os.environ['PREFECT_API_KEY'] = 'your_prefect_cloud_api_key'
asyncio.run(interact_with_prefect_api())
Debug
Known issues
breakingPrefect 2 (and subsequent 3.x releases, which `prefect-client` is part of) introduced significant breaking changes from Prefect 1. Flows written for Prefect 1 will not run directly on Prefect 2/3 without modification. This includes changes to API, deployment model (no more pre-registration), and core concepts.fixConsult the Prefect 1 to Prefect 2 migration guide in the official Prefect documentation. Pin your Prefect version if you rely on Prefect 1 behavior.
affects: 1.x to 2.x, 3.x
gotcha`prefect-client` is a minimal installation and does *not* include the Prefect CLI or local server components. Attempts to run `prefect server start` or use CLI commands will fail, and direct imports of server-related modules (e.g., `prefect.server`) will result in `ModuleNotFoundError`.fixFor full CLI, local server, and agent functionality, install the main `prefect` package (`pip install prefect`). `prefect-client` is specifically for remote API interaction.
affects: All `prefect-client` versions (by design)
gotchaTo connect to Prefect Cloud or a remote Prefect server, `prefect-client` heavily relies on the `PREFECT_API_URL` and `PREFECT_API_KEY` environment variables. If these are not correctly configured, API interactions will fail, often with connection or authentication errors.fixSet `PREFECT_API_URL` to your Prefect server's address (e.g., `http://localhost:4200/api`) or the Prefect Cloud API URL. Set `PREFECT_API_KEY` if your server or Cloud workspace requires authentication. For Prefect Cloud, find API keys in 'Settings > API Keys' in the UI.
affects: All `prefect-client` versions
gotchaSome classes, methods, or objects available for import in the full `prefect` SDK may not be 'runnable' or fully functional within `prefect-client` if they depend on server-oriented functionality (e.g., local agent execution, direct database access).fixIf a feature seems to be missing or fails unexpectedly, verify its compatibility with the `prefect-client`'s remote-interaction-only design. For full SDK features, use the `prefect` package.
affects: All `prefect-client` versions (by design)
gotchaClient and server versions should generally be compatible. While minor discrepancies might work, significant version mismatches between your `prefect-client` and the Prefect server/Cloud can lead to unexpected API errors, incorrect behavior, or features not working as intended.fixKeep your `prefect-client` version at or below the version of the Prefect server or Prefect Cloud instance you are interacting with. Regularly update both components if possible.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prefect.server'
`prefect-client` is a minimal client package and does not include the local Prefect server components or related modules.
fixIf you need to run a local Prefect server or access server-side modules, install the full `prefect` package (`pip install prefect`). `prefect-client` is only for interacting with a remote Prefect instance.
prefect: command not found
The `prefect-client` package does not include the Prefect Command Line Interface (CLI) by design, meaning `prefect` commands are not available on the system path.
fixTo access the Prefect CLI for managing flows, deployments, agents, or the server, install the full `prefect` package (`pip install prefect`).
httpx.ConnectError: [Errno 111] Connect refused | prefect.exceptions.MissingFlowError: Flow 'my-flow' not found
The client could not connect to the specified Prefect API URL, or the deployment/flow does not exist on the connected server. This often happens if `PREFECT_API_URL` or `PREFECT_API_KEY` are unset or incorrect, or the Prefect server is not running.
fixEnsure the Prefect server is running and accessible. Verify that `PREFECT_API_URL` is set correctly to your Prefect API endpoint and `PREFECT_API_KEY` is set if authentication is required.
RuntimeError: No active Prefect client connection. You must be in a client context to perform this action. Use `async with get_client() as client:` or ensure relevant environment variables are set.
An operation requiring a connection to the Prefect API was attempted outside an active client context or without the necessary environment variables (`PREFECT_API_URL`, `PREFECT_API_KEY`) to implicitly establish a connection.
fixWrap your API calls within an `async with get_client() as client:` block, or ensure `PREFECT_API_URL` and `PREFECT_API_KEY` are properly configured in your environment.
Upgrade
Version history
3.7.4latest on PyPI · released Jun 5, 2026
Audit
Dependencies
prefectrequiredProvides the core Prefect SDK components and orchestration engine; `prefect-client` is a minimal subset for remote interaction.