Release v3.0.0 (What’s new?).
Welcome to s3pathlib Documentation¶
s3pathlib is a Python SDK on top of boto3 that works with Amazon S3 the way the standard library pathlib works with local files: build paths, read and write objects, list and filter folders, copy, move and delete them, with or without versioning.
The full guide and the API reference are on Read the Docs.
Install¶
s3pathlib is released on PyPI and needs Python 3.11 or newer:
$ pip install s3pathlib
Quick Look¶
Build paths. This part never calls AWS:
from s3pathlib.api import S3Path
p = S3Path("bucket", "folder", "file.txt") # also S3Path("s3://bucket/folder/file.txt")
p.uri # 's3://bucket/folder/file.txt'
p.key # 'folder/file.txt'
p.parent # S3Path('s3://bucket/folder/')
p.arn # 'arn:aws:s3:::bucket/folder/file.txt'
p.console_url # 'https://console.aws.amazon.com/s3/object/bucket?prefix=folder/file.txt'
Talk to S3. s3pathlib uses the default boto3 client unless you attach your own:
import boto3
from s3pathlib.api import s3_context
s3_context.attach_s3_client(boto3.Session(profile_name="my_profile").client("s3"))
p = S3Path("bucket", "folder", "file.txt")
p.write_text("hello") # returns a new S3Path of the written object
p.read_text() # 'hello'
p.size # 5
folder = S3Path("bucket", "folder/") # a trailing "/" makes it a folder
for csv in folder.iter_objects().filter(S3Path.size >= 1_000_000).filter_by_ext(".csv"):
print(csv.uri)
folder.copy_dir(S3Path("bucket", "backup/"), overwrite=True)
folder.delete() # every object under the folder
S3Path.open gives a file object, so it works with json, csv, pandas and any other library that reads or writes files:
import json
with S3Path("bucket", "config.json").open("w") as f:
json.dump({"name": "alice"}, f)
Using s3pathlib with an AI Coding Agent¶
The pypi-s3pathlib folder is a self-contained Claude Code skill that teaches an AI agent the public API of s3pathlib 3.x. Copy it into the .claude/skills/ folder of your project, and the agent loads it whenever it works with s3pathlib, so it writes code with the current API instead of guessing from older versions.
Upgrading from 2.x¶
3.0.0 is a breaking release; import everything from s3pathlib.api. See the release history and the “Upgrade from 2.x” chapter of the guide.
If you use Claude Code, copy the s3pathlib-upgrade-to-3 folder into the .claude/skills/ folder of your project and run /s3pathlib-upgrade-to-3: it scans your code and notebooks for 2.x usage, rewrites the renames, and walks you through the behavior changes.
Getting Help¶
Ask a question or report a bug on GitHub Issues.
Contributing¶
Please see the Contribution Guidelines.
Copyright¶
s3pathlib is an open source project. See the LICENSE file for more information.