{"id":9148,"library":"ocifs","title":"Oracle Cloud Infrastructure Filesystem (ocifs)","description":"ocifs is a Pythonic filesystem interface to Oracle Cloud Infrastructure (OCI) Object Storage. It builds on top of the `oci` Python SDK and integrates with the `fsspec` (filesystem_spec) ecosystem, allowing applications to interact with OCI Object Storage as if it were a local filesystem. It provides common file-system style operations like `cp`, `mv`, `ls`, `du`, and `open()` for reading and writing data. The current version is 1.3.4, and it is actively maintained by Oracle with a regular release cadence.","status":"active","version":"1.3.4","language":"en","source_language":"en","source_url":"https://github.com/oracle/ocifs","tags":["oracle cloud","oci","object storage","filesystem","fsspec","cloud storage"],"install":[{"cmd":"pip install ocifs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core filesystem abstraction layer that ocifs builds upon.","package":"fsspec","optional":false},{"reason":"Oracle Cloud Infrastructure Python SDK, used for underlying API calls.","package":"oci","optional":false},{"reason":"General-purpose HTTP library, often a transitive dependency.","package":"requests","optional":false}],"imports":[{"symbol":"OCIFileSystem","correct":"from ocifs import OCIFileSystem"}],"quickstart":{"code":"import ocifs\nimport os\n\n# Initialize OCIFileSystem.\n# It will attempt to use default OCI config (~/.oci/config) or Resource Principal/Instance Principal.\n# For explicit config, pass a path or an oci.config object.\n# config_path = os.environ.get('OCI_CONFIG_PATH', '~/.oci/config')\n# fs = ocifs.OCIFileSystem(config=config_path, profile=os.environ.get('OCI_PROFILE', 'DEFAULT'))\n\nfs = ocifs.OCIFileSystem()\n\n# Replace with your bucket and namespace\nbucket_name = 'your_bucket_name'\nnamespace_name = 'your_namespace_name'\n\n# List contents of a bucket\ntry:\n    print(f\"Listing contents of oci://{bucket_name}@{namespace_name}\")\n    items = fs.ls(f'oci://{bucket_name}@{namespace_name}')\n    for item in items:\n        print(item)\nexcept Exception as e:\n    print(f\"Error listing bucket contents: {e}\")\n\n# Example: Write and read a file\nfile_path = f'oci://{bucket_name}@{namespace_name}/test_ocifs.txt'\ndata_to_write = b'Hello, ocifs!'\n\ntry:\n    with fs.open(file_path, 'wb') as f:\n        f.write(data_to_write)\n    print(f\"Successfully wrote to {file_path}\")\n\n    with fs.open(file_path, 'rb') as f:\n        read_data = f.read()\n    print(f\"Successfully read from {file_path}: {read_data}\")\n    assert read_data == data_to_write\n\n    fs.rm(file_path)\n    print(f\"Successfully deleted {file_path}\")\nexcept Exception as e:\n    print(f\"Error during file operations: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize `OCIFileSystem` and perform basic operations like listing objects, writing, and reading a binary file from Oracle Cloud Object Storage. It assumes OCI credentials are configured via a default `~/.oci/config` file or available through Resource/Instance Principals. Remember to replace placeholder bucket and namespace names."},"warnings":[{"fix":"Provide `config` (path to `~/.oci/config` or `oci.config` object) and `profile` arguments, or pass an authenticated `signer` object to `OCIFileSystem` for clarity and control. For example: `fs = ocifs.OCIFileSystem(config='~/.oci/config', profile='MY_PROFILE')` or `from oci.auth.signers import get_resource_principals_signer; signer = get_resource_principals_signer(); fs = ocifs.OCIFileSystem(signer=signer)`.","message":"Authentication to OCI Object Storage can be complex. `OCIFileSystem` attempts to discover credentials (Resource Principal, Instance Principal, or default config file) but explicit configuration is often more reliable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use binary modes (`'rb'`, `'wb'`) when opening files with `ocifs.OCIFileSystem.open()`. Handle text encoding and decoding explicitly in your application code.","message":"`OCIFileSystem.open()` supports binary modes only. Attempting to use text modes (e.g., `'r'`, `'w'`, `'a'`) or arguments like `encoding` will result in errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your `oci` SDK version is compatible with `ocifs` (check `ocifs` release notes or PyPI dependencies for requirements). When troubleshooting, isolate whether the issue is with `ocifs` or the underlying `oci` SDK by attempting basic `oci` SDK operations.","message":" ocifs relies heavily on the `oci` Python SDK. Compatibility issues or misconfigurations within the underlying `oci` SDK can manifest as problems when using ocifs.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install ocifs` to install the library.","cause":"The `ocifs` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'ocifs'"},{"fix":"Remove the `encoding` argument and ensure you are opening the file in binary read (`'rb'`) or binary write (`'wb'`) mode. Handle text encoding/decoding explicitly after reading or before writing bytes.","cause":"`OCIFileSystem.open()` does not support text mode arguments like `encoding` because it only operates in binary mode.","error":"TypeError: OCIFileSystem.open() got an unexpected keyword argument 'encoding'"},{"fix":"Verify that `~/.oci/config` exists and is correctly configured with your OCI credentials. If using a custom path or profile, ensure it's passed explicitly: `fs = ocifs.OCIFileSystem(config='/path/to/my/config', profile='MY_PROFILE')`. Alternatively, ensure Resource Principal or Instance Principal is correctly configured if not using API keys.","cause":"The Oracle Cloud Infrastructure configuration file is missing from its default location, or the specified path/profile is incorrect.","error":"oci.exceptions.ConfigFileNotFound: Config file not found at: ~/.oci/config"}]}