ossfs - fsspec filesystem for Alibaba Cloud OSS

2025.5.0 verified Fri May 01 auth: no python

ossfs provides an fsspec-compatible filesystem interface for Alibaba Cloud Object Storage Service (OSS). Current version is 2025.5.0, with monthly/quarterly releases. It supports both synchronous and asynchronous operations and requires Python >=3.8.

pip install ossfs

Common errors

error ImportError: cannot import name 'OSSFileSystem' from 'ossfs' ↓

cause OSSFileSystem was in a submodule in older versions or not installed correctly.

fix

Update to recent version (>=2023.3.0) and use 'from ossfs import OSSFileSystem'. Ensure package is installed: pip install --upgrade ossfs.

error ModuleNotFoundError: No module named 'aiooss2' ↓

cause Attempting to use AioOSSFileSystem without the async extra.

fix

Install async support: pip install ossfs[async].

error OSS Error: InvalidAccessKeyId. The OSS Access Key Id you provided does not exist in our records. ↓

cause Credentials are incorrect or missing.

fix

Check OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables. Alternatively, use key= and secret= parameters.

error OSS Error: InvalidEndpoint. The endpoint is invalid. ↓

cause Endpoint format incorrect; often includes protocol or is misspelled.

fix

Set endpoint as 'oss-cn-hangzhou.aliyuncs.com' without 'https://'.

Warnings

breaking Prior to 2023.3.0, import path was 'ossfs.core.OSSFileSystem'. After 2023.3.0, it moved to 'ossfs.OSSFileSystem'. Old imports will break. ↓

fix Update import to 'from ossfs import OSSFileSystem'.

gotcha Endpoint must be the region-specific OSS endpoint (e.g., 'oss-cn-hangzhou.aliyuncs.com') and should not include protocol prefix. Including 'https://' will cause connection errors. ↓

fix Set endpoint without protocol: 'oss-cn-hangzhou.aliyuncs.com'.

gotcha When using async filesystem (AioOSSFileSystem), the 'ossfs[async]' extra must be installed. Otherwise, import will fail with ModuleNotFoundError: No module named 'aiooss2'. ↓

fix Install with 'pip install ossfs[async]'.

deprecated Support for Python 3.6 was dropped in version 2023.1.0. ↓

fix Upgrade Python to 3.8+ and ossfs to latest.

Install

pip install ossfs[async]

Imports

OSSFileSystem
wrong
```
from ossfs.core import OSSFileSystem
```
correct
```
from ossfs 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.

Quickstart

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())