Install & Compatibility
Where this runs
tested against v2025.5.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.653s · 63.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.4s · import 1.568s · 66MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OSSFileSystem
✓ from ossfs import OSSFileSystem
✗ from ossfs.core import OSSFileSystem
In older versions OSSFileSystem was in ossfs.core; it was moved to top-level __init__ starting around 2023.4.0.
AioOSSFileSystem
✓ from ossfs import AioOSSFileSystem
Async variant; available only if installed with 'async' extra.
Initialize OSSFileSystem with credentials from environment variables, then use standard fsspec operations.
from ossfs import OSSFileSystem
import os
fs = OSSFileSystem(
key=os.environ.get('OSS_ACCESS_KEY_ID', ''),
secret=os.environ.get('OSS_ACCESS_KEY_SECRET', ''),
endpoint=os.environ.get('OSS_ENDPOINT', ''),
)
# List buckets
print(fs.ls('/'))
# List objects in a bucket
bucket = 'my-bucket'
print(fs.ls(bucket))
# Read a file
with fs.open(f'{bucket}/path/to/file.txt', 'rb') as f:
print(f.read())
Errors
Common errors & fixes
ImportError: cannot import name 'OSSFileSystem' from 'ossfs'
OSSFileSystem was in a submodule in older versions or not installed correctly.
fixUpdate to recent version (>=2023.3.0) and use 'from ossfs import OSSFileSystem'. Ensure package is installed: pip install --upgrade ossfs.
ModuleNotFoundError: No module named 'aiooss2'
Attempting to use AioOSSFileSystem without the async extra.
fixInstall async support: pip install ossfs[async].
OSS Error: InvalidAccessKeyId. The OSS Access Key Id you provided does not exist in our records.
Credentials are incorrect or missing.
fixCheck OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables. Alternatively, use key= and secret= parameters.
OSS Error: InvalidEndpoint. The endpoint is invalid.
Endpoint format incorrect; often includes protocol or is misspelled.
fixSet endpoint as 'oss-cn-hangzhou.aliyuncs.com' without 'https://'.
Upgrade
Version history
2025.5.0latest on PyPI · released May 7, 2025
Audit
Dependencies
fsspecrequiredCore dependency - ossfs implements fsspec AbstractFileSystem protocol.
oss2requiredAliyun OSS SDK for Python; used for low-level OSS API calls.
aiooss2optionalAsync OSS SDK; required for async filesystem features.
aliyun-python-sdk-stsoptionalUsed for STS credential management when assuming roles.