Registry / aws / prefect-aws

prefect-aws

JSON →
library0.7.11pypypi✓ verified 26d ago

Prefect AWS is an integration library for Prefect, a data workflow orchestration and observability platform. It provides battle-tested blocks, tasks, and infrastructure components for seamless interaction with various Amazon Web Services, including ECS, S3, Secrets Manager, Lambda, Batch, and Glue. The current version is 0.7.7 and it receives frequent updates, often aligning with the Prefect core library's release cycle. [1, 4, 24]

pip install prefect-aws
INSTALL
IMPORT
SIG · PREFECT-AWS
P
prefect-aws
awspythonv0.7.11
Install
30.1s avg
Import
7088ms
Disk
294MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.7.11 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 7.232s · 297.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 30.1s · import 6.944s · 300MB
294MB installed
● package 294MB
Code
Verified usage

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

AwsCredentials
from prefect_aws import AwsCredentials
from prefect_aws.credentials import AwsCredentials
AwsCredentials block is directly under the top-level `prefect_aws` package, not a submodule like `credentials`.
S3Bucket
from prefect_aws.s3 import S3Bucket
s3_download
from prefect_aws.s3 import s3_download
SecretsManager
from prefect_aws import SecretsManager
from prefect_aws import AwsSecret
`AwsSecret` was used in older versions/examples, `SecretsManager` is the current block for AWS Secrets Manager. [1, 8, 12]

This quickstart demonstrates how to create and save an `AwsCredentials` block, which is essential for authenticating with AWS services. It then shows how to use this block with `prefect-aws.s3` tasks to upload and download a file from an S3 bucket within a Prefect flow. Remember to replace placeholder values with actual AWS credentials and an existing S3 bucket name. For production, save credentials securely in Prefect Cloud/Server or via environment variables and IAM roles. [1, 4, 8, 13]

import os from prefect import flow, task from prefect_aws import AwsCredentials from prefect_aws.s3 import S3Bucket, s3_upload, s3_download # NOTE: For a real application, create and save the AwsCredentials block in the Prefect UI # or programmatically (as shown below, but typically saved once). # os.environ.get is used here to prevent hardcoding sensitive credentials. @flow def create_and_save_aws_credentials_block(): """Example flow to create and save an AwsCredentials block.""" aws_credentials = AwsCredentials( aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID'), aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_ACCESS_KEY'), region_name=os.environ.get('AWS_REGION', 'us-east-1') ) # Replace 'my-aws-credentials' with your desired block name aws_credentials.save('my-aws-credentials', overwrite=True) print("AwsCredentials block 'my-aws-credentials' saved.") @task async def upload_file_to_s3(bucket_name: str, key: str, content: str): aws_credentials_block = await AwsCredentials.load('my-aws-credentials') await s3_upload( bucket=bucket_name, key=key, text=content, aws_credentials=aws_credentials_block ) print(f"Uploaded '{key}' to s3://{bucket_name}") @task async def download_file_from_s3(bucket_name: str, key: str) -> str: aws_credentials_block = await AwsCredentials.load('my-aws-credentials') downloaded_content = await s3_download( bucket=bucket_name, key=key, aws_credentials=aws_credentials_block ) print(f"Downloaded '{key}' from s3://{bucket_name}") return downloaded_content @flow async def s3_interaction_flow(bucket_name: str = "your-test-bucket"): # Replace with a real bucket name test_key = "prefect-test-file.txt" test_content = "Hello from Prefect AWS!" # Make sure credentials block exists if not await AwsCredentials.exists('my-aws-credentials'): print("AwsCredentials block not found. Run create_and_save_aws_credentials_block() first.") return await upload_file_to_s3(bucket_name, test_key, test_content) downloaded = await download_file_from_s3(bucket_name, test_key) print(f"Content verification: {downloaded == test_content}") if __name__ == "__main__": # First, ensure your AWS credentials block is saved (run this once or use Prefect UI) # os.environ['AWS_ACCESS_KEY_ID'] = '...' # Set actual credentials # os.environ['AWS_SECRET_ACCESS_KEY'] = '...' # Set actual credentials # os.environ['AWS_REGION'] = '...' # Set actual region create_and_save_aws_credentials_block() # Then run the S3 interaction flow (replace 'your-test-bucket' with an actual S3 bucket name) import asyncio asyncio.run(s3_interaction_flow(bucket_name='your-test-bucket'))
prefect --version
Debug
Known issues
breakingPrefect 2 (which `prefect-aws` is built for) introduced significant architectural changes from Prefect 1. Migrating from Prefect 1.x to Prefect 2.x requires updating flow definitions, deployment patterns (Agents vs. Workers), and infrastructure configurations. This is not a direct upgrade path. [19, 29, 30]
fix
Review the official Prefect migration guide from Prefect 1 to Prefect 2. Re-architect flows and deployments to align with Prefect 2 concepts, especially the use of blocks and workers. [29, 30]
affects: All versions of `prefect-aws` (designed for Prefect 2+)
deprecatedThe `ECSTask` infrastructure block has been deprecated and is replaced by the ECS Worker. Users should migrate to the ECS Worker for enhanced functionality, scalability, and better performance. [23]
fix
Migrate from `ECSTask` blocks to using the Prefect ECS Worker and Work Pools. Refer to the Prefect documentation's upgrade guides for agents to workers and ECS worker deployment. [9, 11, 23]
affects: Versions up to `prefect-aws==0.5.x` (ECSTask deprecated in favor of ECS Worker from 0.6.x onwards).
gotchaDirectly embedding AWS Access Key IDs and Secret Access Keys in flow code is insecure and not recommended for production. [1, 4, 12]
fix
Always use `AwsCredentials` blocks, which can be securely saved in the Prefect UI, or leverage AWS IAM roles and environment variables for authentication. Avoid hardcoding sensitive information. [1, 4]
affects: All versions
gotcha`prefect-aws` requires Python >=3.10 as of version 0.7.0. Older Prefect 2.x versions supported Python >=3.7, but this has been updated. [PyPI metadata, 24]
fix
Ensure your Python environment is running version 3.10 or newer. Upgrade Python if necessary.
affects: 0.7.0 and later
gotchaDependency conflicts can arise when installing `prefect-aws` alongside other Prefect extras or other libraries that heavily rely on `boto3`. [25]
fix
Use a dedicated virtual environment. If conflicts occur, inspect dependency trees (`pip install pipdeptree && pipdeptree -p prefect-aws`) and consider pinning specific versions of conflicting packages, especially `boto3` or `botocore`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'prefect_aws.ecs'
This error occurs when the `prefect-aws` package, or specifically its `ecs` submodule, is not installed or accessible in the Python environment where Prefect is trying to load it. This can happen after Prefect core upgrades or if the package was not installed correctly.
fix
Install the `prefect-aws` package and register its blocks: `pip install -U prefect-aws` followed by `prefect block register -m prefect_aws`.
botocore.exceptions.NoCredentialsError: Unable to locate credentials
This error indicates that Prefect-AWS components (e.g., S3Bucket, ECSWorker) cannot find valid AWS credentials to authenticate with AWS services. This often stems from incorrectly configured `AwsCredentials` blocks or missing environment variables.
fix
Ensure you have created and saved an `AwsCredentials` block in Prefect with your AWS access key ID and secret access key. When using `S3Bucket` or other AWS blocks that require credentials, ensure you pass the loaded `AwsCredentials` block using the `credentials` parameter, e.g., `S3Bucket(..., credentials=aws_credentials_block)` rather than `aws_credentials`.
An error occurred (InvalidParameterException) when calling the RunTask operation: The specified capacity provider strategy cannot contain a capacity provider that is not associated with the cluster.
This error happens when deploying a Prefect flow to an AWS ECS Fargate cluster where the specified capacity provider strategy in the ECS task definition includes a capacity provider that is not correctly associated with the target ECS cluster.
fix
Verify your AWS ECS cluster configuration. Ensure that the capacity provider specified in your ECS task definition's capacity provider strategy is indeed associated with the ECS cluster you are targeting. This configuration needs to be managed within AWS, outside of Prefect.
AttributeError: 'ECSWorker' object has no attribute 'work_pool'. Did you mean: '_work_pool'?
This `AttributeError` typically occurs due to an internal change in the `prefect-aws` library or the Prefect core library, where the `ECSWorker` class's attribute for accessing the work pool was renamed or refactored (e.g., from `work_pool` to `_work_pool`). This is often a version incompatibility issue.
fix
Update `prefect-aws` and Prefect to their latest compatible versions. If the error persists, consult the `prefect-aws` documentation or GitHub issues for any breaking changes related to `ECSWorker` configuration in your specific versions. Downgrading to a known working version of `prefect-aws` (e.g., `prefect-aws<0.5.6` as per a community report) might also resolve it temporarily.
TypeError: unhashable type: 'dict' (when assigning AWS Client Parameters to an S3 bucket block in the UI)
When creating or updating an `S3Bucket` block via the Prefect UI, if the 'Client Parameters' field is incorrectly storing a dictionary (e.g., directly from an `AwsCredentials` block) rather than expected key-value pairs, it can lead to a `TypeError` because dictionaries are unhashable.
fix
Ensure that 'Client Parameters' for `S3Bucket` blocks in the Prefect UI are configured with individual string key-value pairs, rather than attempting to directly assign a dictionary object. If setting programmatically, provide parameters as a dictionary of strings or ensure the `AwsCredentials` object is correctly integrated as per the `prefect-aws` library's intended usage.
Upgrade
Version history
0.7.11latest on PyPI · released Aug 5, 2026
Audit
Dependencies
prefectrequiredCore Prefect library is required for orchestration and workflow definition. Version 0.7.7 of prefect-aws requires prefect>=3.6.24.
boto3requiredUnderlying AWS SDK for Python. Although abstracted by prefect-aws, it's fundamental for AWS interactions.
Agent activity
40 hits · last 30 days
node
36
OpenAI (training)
1
Resources
prefect-aws — pip install prefect-aws · libregistry