{"id":24186,"library":"ossfs","title":"ossfs - fsspec filesystem for Alibaba Cloud OSS","description":"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.","status":"active","version":"2025.5.0","language":"python","source_language":"en","source_url":"https://github.com/fsspec/ossfs","tags":["fsspec","oss","alibaba-cloud","filesystem","object-storage"],"install":[{"cmd":"pip install ossfs","lang":"bash","label":"default"},{"cmd":"pip install ossfs[async]","lang":"bash","label":"with async support"}],"dependencies":[{"reason":"Core dependency - ossfs implements fsspec AbstractFileSystem protocol.","package":"fsspec","optional":false},{"reason":"Aliyun OSS SDK for Python; used for low-level OSS API calls.","package":"oss2","optional":false},{"reason":"Async OSS SDK; required for async filesystem features.","package":"aiooss2","optional":true},{"reason":"Used for STS credential management when assuming roles.","package":"aliyun-python-sdk-sts","optional":true}],"imports":[{"note":"In older versions OSSFileSystem was in ossfs.core; it was moved to top-level __init__ starting around 2023.4.0.","wrong":"from ossfs.core import OSSFileSystem","symbol":"OSSFileSystem","correct":"from ossfs import OSSFileSystem"},{"note":"Async variant; available only if installed with 'async' extra.","wrong":"","symbol":"AioOSSFileSystem","correct":"from ossfs import AioOSSFileSystem"}],"quickstart":{"code":"from ossfs import OSSFileSystem\nimport os\n\nfs = OSSFileSystem(\n    key=os.environ.get('OSS_ACCESS_KEY_ID', ''),\n    secret=os.environ.get('OSS_ACCESS_KEY_SECRET', ''),\n    endpoint=os.environ.get('OSS_ENDPOINT', ''),\n)\n\n# List buckets\nprint(fs.ls('/'))\n\n# List objects in a bucket\nbucket = 'my-bucket'\nprint(fs.ls(bucket))\n\n# Read a file\nwith fs.open(f'{bucket}/path/to/file.txt', 'rb') as f:\n    print(f.read())","lang":"python","description":"Initialize OSSFileSystem with credentials from environment variables, then use standard fsspec operations."},"warnings":[{"fix":"Update import to 'from ossfs import OSSFileSystem'.","message":"Prior to 2023.3.0, import path was 'ossfs.core.OSSFileSystem'. After 2023.3.0, it moved to 'ossfs.OSSFileSystem'. Old imports will break.","severity":"breaking","affected_versions":"<2023.3.0"},{"fix":"Set endpoint without protocol: 'oss-cn-hangzhou.aliyuncs.com'.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Install with 'pip install ossfs[async]'.","message":"When using async filesystem (AioOSSFileSystem), the 'ossfs[async]' extra must be installed. Otherwise, import will fail with ModuleNotFoundError: No module named 'aiooss2'.","severity":"gotcha","affected_versions":">=2023.4.0"},{"fix":"Upgrade Python to 3.8+ and ossfs to latest.","message":"Support for Python 3.6 was dropped in version 2023.1.0.","severity":"deprecated","affected_versions":"<2023.1.0"}],"env_vars":null,"search_vec":"'2025.5.0':26 '3.8':40 'alibaba':5,17,44 'alibaba-cloud':43 'asynchron':35 'cloud':6,18,45 'compat':13 'current':23 'filesystem':3,14,46 'fsspec':2,12,41 'fsspec-compat':11 'interfac':15 'monthly/quarterly':28 'object':19,48 'object-storag':47 'oper':36 'oss':7,22,42 'ossf':1,8 'provid':9 'python':39 'releas':29 'requir':38 'servic':21 'storag':20,49 'support':31 'synchron':33 'version':24","created_at":"2026-05-01T08:11:44.865914+00:00","updated_at":"2026-05-01T08:11:44.865914+00:00","problems":[{"fix":"Update to recent version (>=2023.3.0) and use 'from ossfs import OSSFileSystem'. Ensure package is installed: pip install --upgrade ossfs.","cause":"OSSFileSystem was in a submodule in older versions or not installed correctly.","error":"ImportError: cannot import name 'OSSFileSystem' from 'ossfs'"},{"fix":"Install async support: pip install ossfs[async].","cause":"Attempting to use AioOSSFileSystem without the async extra.","error":"ModuleNotFoundError: No module named 'aiooss2'"},{"fix":"Check OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables. Alternatively, use key= and secret= parameters.","cause":"Credentials are incorrect or missing.","error":"OSS Error: InvalidAccessKeyId. The OSS Access Key Id you provided does not exist in our records."},{"fix":"Set endpoint as 'oss-cn-hangzhou.aliyuncs.com' without 'https://'.","cause":"Endpoint format incorrect; often includes protocol or is misspelled.","error":"OSS Error: InvalidEndpoint. The endpoint is invalid."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2025.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/fsspec/ossfs","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ossfs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","database","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}