{"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,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","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,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}