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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 7.232s · 297.9MB
glibcpy 3.10–3.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]fixReview 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]fixMigrate 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]fixAlways 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]fixEnsure 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]fixUse 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.
fixInstall 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.
fixEnsure 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.
fixVerify 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.
fixUpdate `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.
fixEnsure 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.