Registry / aws / ocifs
library1.3.4pypypi✓ verified 85d ago

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.

pip install ocifs
INSTALL
IMPORT
SIG · OCIFS
O
ocifs
awspythonv1.3.4
Install
21.5s avg
Import
1613ms
Disk
493MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.656s · 474.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 21.5s · import 1.571s · 475MB
493MB installed
● package 493MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OCIFileSystem
from ocifs import OCIFileSystem

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}")
Debug
Known issues
gotchaAuthentication 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)`.
affects: All versions
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.
affects: All versions
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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ocifs'
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'
`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
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.
Upgrade
Version history
1.3.4latest on PyPI · released Nov 6, 2025
Audit
Dependencies
fsspecrequiredCore filesystem abstraction layer that ocifs builds upon.
ocirequiredOracle Cloud Infrastructure Python SDK, used for underlying API calls.
requestsrequiredGeneral-purpose HTTP library, often a transitive dependency.
Agent activity
12 hits · last 30 days
node
12
Resources
ocifs — pip install ocifs · libregistry