{"id":9194,"library":"prefect-client","title":"Prefect Client","description":"Prefect Client is a lightweight Python library providing essential client-side functionality for interacting with Prefect Cloud or a self-hosted Prefect server instance. It's designed for ephemeral execution environments like AWS Lambda, omitting the full Prefect SDK's CLI and local server components. The current version is 3.6.26, and it follows the active release cadence of the main Prefect project, including frequent stable and nightly builds.","status":"active","version":"3.6.26","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect","tags":["workflow-orchestration","data-engineering","api-client","cloud-integration","remote-execution","lambda","etl","mlops"],"install":[{"cmd":"pip install prefect-client","lang":"bash","label":"Install Prefect Client"},{"cmd":"pip install prefect","lang":"bash","label":"Install full Prefect SDK (for local orchestration/server)"}],"dependencies":[{"reason":"Provides the core Prefect SDK components and orchestration engine; `prefect-client` is a minimal subset for remote interaction.","package":"prefect","optional":false}],"imports":[{"note":"Used to remotely trigger a deployed flow on a Prefect server or Cloud.","symbol":"run_deployment","correct":"from prefect.deployments import run_deployment"},{"note":"For emitting custom events that can be captured by Prefect automations.","symbol":"emit_event","correct":"from prefect.events import emit_event"},{"note":"`get_client` is the recommended asynchronous context manager for API interaction; direct `PrefectClient` instantiation is less common and often requires manual lifecycle management.","wrong":"from prefect.client import PrefectClient","symbol":"get_client","correct":"from prefect.client.orchestration import get_client"}],"quickstart":{"code":"import os\nimport asyncio\nfrom prefect.deployments import run_deployment\nfrom prefect.client.orchestration import get_client\n\n# Ensure API URL and Key are set as environment variables for remote connection\nos.environ['PREFECT_API_URL'] = os.environ.get('PREFECT_API_URL', 'http://localhost:4200/api')\nos.environ['PREFECT_API_KEY'] = os.environ.get('PREFECT_API_KEY', 'your_api_key_if_needed')\n\nasync def interact_with_prefect_api():\n    print(f\"Connecting to Prefect API at: {os.environ['PREFECT_API_URL']}\")\n    async with get_client() as client:\n        # Example 1: Remotely trigger a deployment\n        try:\n            flow_run = await run_deployment(\n                name=\"my-flow/my-deployment\",\n                parameters={\"message\": \"Hello from prefect-client!\"},\n                timeout=0 # Do not wait for the flow run to complete\n            )\n            print(f\"Triggered flow run: {flow_run.name} (ID: {flow_run.id})\")\n        except Exception as e:\n            print(f\"Could not trigger deployment: {e}. Ensure 'my-flow/my-deployment' exists and is accessible.\")\n\n        # Example 2: Read some information from the API\n        try:\n            deployments = await client.read_deployments(limit=5)\n            print(f\"\\nFound {len(deployments)} deployments:\")\n            for dep in deployments:\n                print(f\"  - {dep.name} (ID: {dep.id})\")\n        except Exception as e:\n            print(f\"Could not read deployments: {e}. Check API URL/Key and server status.\")\n\nif __name__ == \"__main__\":\n    # Note: If connecting to Prefect Cloud, ensure PREFECT_API_KEY is set\n    # os.environ['PREFECT_API_KEY'] = 'your_prefect_cloud_api_key'\n    asyncio.run(interact_with_prefect_api())\n","lang":"python","description":"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."},"warnings":[{"fix":"Consult the Prefect 1 to Prefect 2 migration guide in the official Prefect documentation. Pin your Prefect version if you rely on Prefect 1 behavior.","message":"Prefect 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.","severity":"breaking","affected_versions":"1.x to 2.x, 3.x"},{"fix":"For full CLI, local server, and agent functionality, install the main `prefect` package (`pip install prefect`). `prefect-client` is specifically for remote API interaction.","message":"`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`.","severity":"gotcha","affected_versions":"All `prefect-client` versions (by design)"},{"fix":"Set `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.","message":"To 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.","severity":"gotcha","affected_versions":"All `prefect-client` versions"},{"fix":"If 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.","message":"Some 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).","severity":"gotcha","affected_versions":"All `prefect-client` versions (by design)"},{"fix":"Keep 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.","message":"Client 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If 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.","cause":"`prefect-client` is a minimal client package and does not include the local Prefect server components or related modules.","error":"ModuleNotFoundError: No module named 'prefect.server'"},{"fix":"To access the Prefect CLI for managing flows, deployments, agents, or the server, install the full `prefect` package (`pip install prefect`).","cause":"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.","error":"prefect: command not found"},{"fix":"Ensure 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.","cause":"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.","error":"httpx.ConnectError: [Errno 111] Connect refused | prefect.exceptions.MissingFlowError: Flow 'my-flow' not found"},{"fix":"Wrap 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.","cause":"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.","error":"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."}]}