Oracle Cloud Infrastructure Filesystem (ocifs)

1.3.4 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'ocifs'
```
cause The `ocifs` library is not installed in the current Python environment.

fix Run `pip install ocifs` to install the library.
```
TypeError: OCIFileSystem.open() got an unexpected keyword argument 'encoding'
```
cause `OCIFileSystem.open()` does not support text mode arguments like `encoding` because it only operates in binary mode.

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.
```
oci.exceptions.ConfigFileNotFound: Config file not found at: ~/.oci/config
```
cause The Oracle Cloud Infrastructure configuration file is missing from its default location, or the specified path/profile is incorrect.

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.

Warnings

gotcha 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.
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)`.
gotcha `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.
Fix: Always use binary modes (`'rb'`, `'wb'`) when opening files with `ocifs.OCIFileSystem.open()`. Handle text encoding and decoding explicitly in your application code.
gotcha ocifs relies heavily on the `oci` Python SDK. Compatibility issues or misconfigurations within the underlying `oci` SDK can manifest as problems when using ocifs.
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.

Install

pip install ocifs Install latest version

Imports

OCIFileSystem
```
from ocifs import OCIFileSystem
```

Quickstart

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.

import ocifs
import os

# Initialize OCIFileSystem.
# It will attempt to use default OCI config (~/.oci/config) or Resource Principal/Instance Principal.
# For explicit config, pass a path or an oci.config object.
# config_path = os.environ.get('OCI_CONFIG_PATH', '~/.oci/config')
# fs = ocifs.OCIFileSystem(config=config_path, profile=os.environ.get('OCI_PROFILE', 'DEFAULT'))

fs = ocifs.OCIFileSystem()

# Replace with your bucket and namespace
bucket_name = 'your_bucket_name'
namespace_name = 'your_namespace_name'

# List contents of a bucket
try:
    print(f"Listing contents of oci://{bucket_name}@{namespace_name}")
    items = fs.ls(f'oci://{bucket_name}@{namespace_name}')
    for item in items:
        print(item)
except Exception as e:
    print(f"Error listing bucket contents: {e}")

# Example: Write and read a file
file_path = f'oci://{bucket_name}@{namespace_name}/test_ocifs.txt'
data_to_write = b'Hello, ocifs!'

try:
    with fs.open(file_path, 'wb') as f:
        f.write(data_to_write)
    print(f"Successfully wrote to {file_path}")

    with fs.open(file_path, 'rb') as f:
        read_data = f.read()
    print(f"Successfully read from {file_path}: {read_data}")
    assert read_data == data_to_write

    fs.rm(file_path)
    print(f"Successfully deleted {file_path}")
except Exception as e:
    print(f"Error during file operations: {e}")

view raw JSON →