{"id":2268,"library":"s3path","title":"s3path","description":"s3path offers a Pythonic, object-oriented interface for working with AWS S3 objects and directories, mirroring the standard library's `pathlib` module. It seamlessly integrates with `boto3` to provide a convenient filesystem-like experience for S3 buckets. The current version is 0.6.5, with consistent updates and patch releases.","status":"active","version":"0.6.5","language":"python","source_language":"en","source_url":"https://github.com/liormizr/s3path","tags":["aws","s3","pathlib","filesystem","cloud-storage"],"install":[{"cmd":"pip install s3path","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Required for interacting with the AWS S3 service as s3path's underlying driver. Version 0.5.8 added support for Boto3 1.35.x.","package":"boto3"},{"reason":"Utilized by S3Path.open() for handling file streaming operations.","package":"smart_open"}],"imports":[{"note":"The primary class for interacting with S3 paths.","symbol":"S3Path","correct":"from s3path import S3Path"},{"note":"For path manipulation without requiring AWS API calls.","symbol":"PureS3Path","correct":"from s3path import PureS3Path"},{"note":"For working with S3 objects in versioned buckets.","symbol":"VersionedS3Path","correct":"from s3path import VersionedS3Path"},{"note":"Provides access to boto3 resource configuration (added in 0.5.7).","symbol":"configuration_map","correct":"from s3path import configuration_map"}],"quickstart":{"code":"import os\nimport boto3\nfrom s3path import S3Path\n\n# Configure boto3 session (recommended for programmatic access)\n# Replace with your actual region and credentials or profile\n# For local testing, ensure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set\nboto3.setup_default_session(\n    region_name=os.environ.get('AWS_REGION', 'us-east-1'),\n    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'test'),\n    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'test')\n)\n\nbucket_name = 'your-s3-bucket'\nfile_key = 'my-folder/my-file.txt'\n\n# Create an S3Path object\ns3_path = S3Path(f'/{bucket_name}/{file_key}')\nprint(f\"S3 Path: {s3_path}\")\n\n# Check if the file exists (requires S3 interaction)\nif not s3_path.exists():\n    print(f\"Creating file: {s3_path}\")\n    s3_path.write_text('Hello from s3path!')\n    print(\"File created.\")\nelse:\n    print(f\"File '{s3_path}' already exists.\")\n\n# Read content\ncontent = s3_path.read_text()\nprint(f\"Content of '{s3_path}': {content}\")\n\n# List contents of a directory-like prefix\ndirectory_path = S3Path(f'/{bucket_name}/my-folder/')\nprint(f\"\\nListing contents of '{directory_path}':\")\nfor p in directory_path.iterdir():\n    print(f\" - {p}\")\n\n# Clean up (optional)\n# s3_path.unlink() # Uncomment to delete the file\n# print(f\"Deleted {s3_path}\")","lang":"python","description":"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()`."},"warnings":[{"fix":"Upgrade Python environment to 3.9 or higher.","message":"Version 0.6.0 removed support for Python 3.8 and introduced support for Python 3.14. Projects still on Python 3.8 will need to upgrade their Python version before upgrading s3path.","severity":"breaking","affected_versions":"0.6.0 and later"},{"fix":"Remove any `glob_new_algorithm` configurations. The new algorithm is now the default and only option.","message":"From version 0.6.0, the `glob` and `rglob` methods exclusively use a new, optimized algorithm. The `glob_new_algorithm` configuration parameter, previously used to switch algorithms, is now deprecated and its functionality removed.","severity":"breaking","affected_versions":"0.6.0 and later"},{"fix":"Upgrade to version 0.6.5 or newer to ensure accurate existence checks.","message":"The `.exists()` method in versions prior to 0.6.5 could return `True` for partial key matches (e.g., querying for 'foo' would return true if 'foobar' existed). This was fixed in 0.6.5 to correctly use `ListObjectsV2`.","severity":"gotcha","affected_versions":"<0.6.5"},{"fix":"Be aware that performance for `is_dir` in 0.6.3+ does not include this specific caching mechanism.","message":"A caching system for the `is_dir` method was introduced in 0.6.2 but subsequently reverted and removed in 0.6.3 due to issues. Relying on this caching for performance in intermediate 0.6.2 releases is not advised.","severity":"gotcha","affected_versions":"0.6.2"},{"fix":"Prefer `S3Path.glob('**/*', ...)` for recursive directory traversal when possible.","message":"The `walk` method can be very heavy on AWS S3 API calls, potentially leading to increased costs and slower performance, especially for large buckets. It is generally recommended to use recursive `glob` instead for most traversal needs.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Remove usage of this configuration parameter; it no longer has an effect.","message":"The `glob_new_algorithm` configuration parameter, used to switch glob algorithms, entered a deprecation cycle in version 0.6.0 as the new algorithm became the sole implementation.","severity":"deprecated","affected_versions":"0.6.0 and later"},{"fix":"Upgrade to version 0.6.3 or newer to patch this security vulnerability.","message":"Version 0.6.3 fixed a null encryption key vulnerability. Older versions might be susceptible to this security flaw.","severity":"breaking","affected_versions":"<0.6.3"}],"env_vars":null,"search_vec":"'0.6.5':45 'aw':13,52 'boto3':29 'bucket':40 'cloud':57 'cloud-storag':56 'consist':47 'conveni':33 'current':42 'directori':17 'experi':37 'filesystem':35,55 'filesystem-lik':34 'integr':27 'interfac':9 'librari':21 'like':36 'mirror':18 'modul':24 'object':7,15 'object-ori':6 'offer':3 'orient':8 'patch':50 'pathlib':23,54 'provid':31 'python':5 'releas':51 's3':14,39,53 's3path':1,2 'seamless':26 'standard':20 'storag':58 'updat':48 'version':43 'work':11","created_at":"2026-04-09T18:50:42.568190+00:00","updated_at":"2026-04-16T21:15:44.357966+00:00","problems":[{"fix":"Before performing operations, check if the S3 object exists using `s3path.S3Path.exists()`. Ensure the bucket and key in the path are correct.","cause":"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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 's3://your-bucket/path/to/non-existent-file'"},{"fix":"Verify 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.","cause":"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.","error":"botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the GetObject operation: Access Denied."},{"fix":"Use directory-specific methods like `iterdir()` or `glob()` to list contents, or ensure the `S3Path` object points to a specific file, not a directory.","cause":"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 `/`).","error":"IsADirectoryError: [Errno 21] Is a directory: 's3://your-bucket/path/to/directory/'"},{"fix":"Initialize `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.","cause":"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.","error":"ValueError: bucket is required when path does not contain a bucket"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.5","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/liormizr/s3path","docs":null,"changelog":null,"pypi":"https://pypi.org/project/s3path/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","type-stubs","data","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}