Install & Compatibility
Where this runs
tested against v0.6.5 · 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 0.522s · 52.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.4s · import 0.452s · 53MB
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
S3Path
✓ from s3path import S3Path
The primary class for interacting with S3 paths.
PureS3Path
✓ from s3path import PureS3Path
For path manipulation without requiring AWS API calls.
VersionedS3Path
✓ from s3path import VersionedS3Path
For working with S3 objects in versioned buckets.
configuration_map
✓ from s3path import configuration_map
Provides access to boto3 resource configuration (added in 0.5.7).
This example demonstrates how to initialize `S3Path`, configure the underlying `boto3` session using environment variables, write text to an S3 object, read its content, and list objects within an S3 prefix using `iterdir()`.
import os
import boto3
from s3path import S3Path
# Configure boto3 session (recommended for programmatic access)
# Replace with your actual region and credentials or profile
# For local testing, ensure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set
boto3.setup_default_session(
region_name=os.environ.get('AWS_REGION', 'us-east-1'),
aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'test'),
aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'test')
)
bucket_name = 'your-s3-bucket'
file_key = 'my-folder/my-file.txt'
# Create an S3Path object
s3_path = S3Path(f'/{bucket_name}/{file_key}')
print(f"S3 Path: {s3_path}")
# Check if the file exists (requires S3 interaction)
if not s3_path.exists():
print(f"Creating file: {s3_path}")
s3_path.write_text('Hello from s3path!')
print("File created.")
else:
print(f"File '{s3_path}' already exists.")
# Read content
content = s3_path.read_text()
print(f"Content of '{s3_path}': {content}")
# List contents of a directory-like prefix
directory_path = S3Path(f'/{bucket_name}/my-folder/')
print(f"\nListing contents of '{directory_path}':")
for p in directory_path.iterdir():
print(f" - {p}")
# Clean up (optional)
# s3_path.unlink() # Uncomment to delete the file
# print(f"Deleted {s3_path}")
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 's3://your-bucket/path/to/non-existent-file'
This error occurs when attempting to perform an operation (like `open()`, `read_text()`, `stat()`) on an S3 object path that does not exist in the specified bucket.
fixBefore performing operations, check if the S3 object exists using `s3path.S3Path.exists()`. Ensure the bucket and key in the path are correct.
botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the GetObject operation: Access Denied.
This error indicates that the AWS credentials used by `boto3` (and thus `s3path`) lack the necessary IAM permissions to perform the requested S3 operation on the specified bucket or object.
fixVerify that your AWS IAM role or user has the appropriate S3 permissions (e.g., `s3:GetObject`, `s3:PutObject`, `s3:ListBucket`) for the target bucket and objects.
IsADirectoryError: [Errno 21] Is a directory: 's3://your-bucket/path/to/directory/'
You are attempting to use a file-specific method like `open()`, `read_text()`, or `write_text()` on an `S3Path` object that represents an S3 'directory' (a prefix ending with `/`).
fixUse directory-specific methods like `iterdir()` or `glob()` to list contents, or ensure the `S3Path` object points to a specific file, not a directory.
ValueError: bucket is required when path does not contain a bucket
This error is raised when an `S3Path` object is initialized with a relative path or an incomplete S3 URI that does not explicitly include a bucket name.
fixInitialize `S3Path` with a full S3 URI including the bucket name (e.g., `s3path.S3Path('s3://my-bucket/my-file.txt')`) or ensure it's a subpath of an `S3Path` object that already defines a bucket. Upgrade
Version history
0.6.5latest on PyPI · released Jan 24, 2026
Audit
Dependencies
boto3requiredRequired for interacting with the AWS S3 service as s3path's underlying driver. Version 0.5.8 added support for Boto3 1.35.x.
smart_openrequiredUtilized by S3Path.open() for handling file streaming operations.