Registry / http-networking / universal-pathlib

universal-pathlib

JSON →
library0.3.10pypypi✓ verified 24d ago

Universal Pathlib is a Python library that extends the `pathlib.Path` interface to provide a unified, Pythonic way of interacting with a wide variety of backend filesystems, including local, cloud storage (S3, GCS, Azure), HTTP(S), and more, by leveraging `fsspec` backends. It is currently at version 0.3.10 and maintains a regular release cadence with frequent updates and bug fixes.

pip install universal-pathlib
INSTALL
IMPORT
SIG · UNIVERSAL-PATHLIB
U
universal-pathlib
http-networkingpythonv0.3.10
Install
6.8s avg
Import
336ms
Disk
34MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.10 · 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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.358s · 20.2MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 6.8s · import 0.314s · 21MB
34MB installed
● package 34MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

UPath
from upath import UPath

This quickstart demonstrates how to use `UPath` for both a remote S3 bucket and a local file. It shows common operations like writing text, reading text, checking existence, and iterating directory contents. For S3, ensure `s3fs` is installed and AWS credentials are configured (e.g., via environment variables or `~/.aws/credentials`). For actual usage, replace `your-test-s3-bucket` with an accessible S3 bucket.

import os from upath import UPath # Example for S3 (requires 's3fs' to be installed and AWS credentials configured) # You can use environment variables for credentials or pass storage_options S3_BUCKET = os.environ.get('S3_TEST_BUCKET', 'your-test-s3-bucket') S3_KEY = 'example.txt' # Create a UPath object for an S3 location s3path = UPath(f"s3://{S3_BUCKET}") / S3_KEY # Write content to the S3 file try: s3path.write_text('Hello from Universal Pathlib!') print(f"Successfully wrote to {s3path}.") # Read content from the S3 file content = s3path.read_text() print(f"Content of {s3path}: '{content}'.") # Check if the path exists print(f"Does {s3path} exist? {s3path.exists()}.") # List contents of the parent directory (if bucket exists and is not empty) print(f"Listing contents of {s3path.parent}:") for p in s3path.parent.iterdir(): print(f" - {p}") finally: # Clean up: delete the created file if s3path.exists(): s3path.unlink() print(f"Cleaned up: deleted {s3path}.") # Example for a local file (no additional fsspec backend needed) local_path = UPath("local_example.txt") local_path.write_text("This is a local file.") print(f"Local file content: {local_path.read_text()}") local_path.unlink()
Debug
Known issues
breakingThe `_protocol_dispatch=False` argument for extending the UPath API has been deprecated. Using it may lead to incorrect behavior or be removed in future versions.
fix
Migrate to subclassing `upath.extensions.ProxyUPath` for extending the API. Consult the official documentation for `ProxyUPath` usage examples.
affects: >=0.3.4
gotchaAttempting to instantiate a specific `UPath` subclass (e.g., `S3Path`) with a path string for a different protocol (e.g., `http://` or `file://`) will now raise a `TypeError` due to protocol incompatibility, rather than silently failing or using an incorrect backend.
fix
Ensure the protocol in the path string matches the `UPath` subclass being instantiated, or use the base `UPath` class which dispatches to the correct subclass based on the protocol.
affects: >=0.3.9
gotchaWhile `UPath` can attempt to handle any `fsspec`-compatible protocol, explicit implementations are tested and guaranteed. If no specialized `UPath` implementation exists for a given protocol, `UPath` will return a generic instance, but its behavior might not be fully reliable or tested.
fix
Prioritize using protocols with explicitly supported `UPath` implementations listed in the documentation. If using an untested protocol, thoroughly test its behavior and consider contributing an implementation if issues arise.
affects: All versions
breakingOperations on S3Path (and potentially other cloud storage paths) require proper AWS credentials to be configured in the environment (e.g., via environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, or AWS config files).
fix
Ensure AWS credentials are correctly configured for the environment where the Python script is being run. Refer to the AWS documentation on configuring credentials for details (e.g., using environment variables, IAM roles, or the AWS CLI config file).
affects: All versions
breakingWhen interacting with cloud storage services like S3, proper authentication credentials must be configured in the environment (e.g., AWS environment variables, credential files, or IAM roles). Without credentials, operations will fail with a `NoCredentialsError`.
fix
Ensure that the execution environment has the necessary AWS credentials configured according to AWS best practices (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY environment variables, or an ~/.aws/credentials file).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'upath'
The 'universal-pathlib' library has not been installed, or there's a typo in the import statement.
fix
pip install universal-pathlib
ModuleNotFoundError: No module named 'universal_pathlib'
The user is attempting to import using the package installation name 'universal_pathlib' instead of the aliased module name 'upath'.
fix
from upath import UPath
ImportError: cannot import name 'Path' from 'upath'
The user is trying to import a class named 'Path' from the 'upath' module, but the correct class name is 'UPath'.
fix
from upath import UPath
fsspec.exceptions.NoBackendError: No backend found for 's3'
The required fsspec backend package for the specified protocol (e.g., 's3fs' for S3, 'gcsfs' for GCS) is not installed.
fix
pip install s3fs
Upgrade
Version history
0.3.10latest on PyPI · released Feb 22, 2026
Audit
Dependencies
fsspecrequiredCore dependency for connecting to various filesystems.
s3fsoptionalRequired for AWS S3 filesystem support.
gcsfsoptionalRequired for Google Cloud Storage (GCS) support.
adlfsoptionalRequired for Azure Storage (Azure Data Lake Storage Gen1 and Gen2) support.
huggingface_huboptionalRequired for Hugging Face filesystem support.
paramikooptionalRequired for SFTP and SSH filesystems.
smbprotocoloptionalRequired for SMB filesystems.
webdav4[fsspec]optionalRequired for WebDAV-based filesystems.
Agent activity
41 hits · last 30 days
node
36
OpenAI (training)
1
Resources
universal-pathlib — pip install universal-pathlib · libregistry