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 s3pathlibQuick 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 folderS3Path.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.
2 maintainers
Metadata
2 maintainers
Release files for s3pathlib 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| s3pathlib-3.0.0.tar.gz | 103.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| s3pathlib-3.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 216.2 kB
Release files / s3pathlib-3.0.0.tar.gz
| Download URL | s3pathlib-3.0.0.tar.gz |
|---|---|
| Size | 103.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8c1c16742ce911ac7bfde27d7c174a92c0bcd3cbed8765f60a39d6fed12e3aa1
|
|
BLAKE2b-256 checksum How to use checksums |
ec0c08bc840eb92e39139a9f4a641ca6ce42a8792d87227a361c67a4c14b1342
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / s3pathlib-3.0.0-py3-none-any.whl
| Download URL | s3pathlib-3.0.0-py3-none-any.whl |
|---|---|
| Size | 112.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
809e63003dffcd8a3787a0cab0c7f7d165878d4c92e184a23a2075d9ace46adb
|
|
BLAKE2b-256 checksum How to use checksums |
4ed7caa5cefc30953851524ec1a23feaeed861a75c058c04056a13cc4760bf27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
