Install & Compatibility
Where this runs
tested against v3.3.0 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.327s · 30MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.3s · import 0.296s · 31MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
iRODSSession
✓ from irods.session import iRODSSession
✗ from irodsclient import iRODSSession
The main entry point for interaction is within the 'irods.session' submodule, not directly from 'irodsclient'.
Collection
✓ from irods.collection import iRODSCollection
✗ from irods.collection import Collection
The class name for collections is iRODSCollection.
DataObject
✓ from irods.data_object import iRODSDataObject
✗ from irods.data_object import DataObject
The class name for data objects is iRODSDataObject.
This quickstart demonstrates how to establish a session with an iRODS server using environment variables for credentials and then list the contents of the user's home collection. It uses `iRODSSession` as the main entry point for all interactions and showcases basic collection traversal.
import os
from irods.session import iRODSSession
# Configure iRODS connection parameters using environment variables or defaults
host = os.environ.get('IRODS_HOST', 'localhost')
port = int(os.environ.get('IRODS_PORT', '1247'))
zone = os.environ.get('IRODS_ZONE', 'tempZone')
user = os.environ.get('IRODS_USER', 'rods')
password = os.environ.get('IRODS_PASSWORD', 'rods')
try:
# Establish a session with iRODS
with iRODSSession(host=host, port=port, zone=zone, user=user, password=password) as session:
print(f"Successfully connected to iRODS zone: {session.zone} as user: {session.user}")
# Example: List the contents of the user's home collection
home_collection_path = f'/{session.zone}/home/{session.user}'
print(f"\nListing contents of: {home_collection_path}")
try:
collection = session.collections.get(home_collection_path)
for item in collection.data_objects:
print(f" Data Object: {item.name} (size: {item.size})")
for sub_collection in collection.subcollections:
print(f" Sub-Collection: {sub_collection.name}")
except Exception as e:
print(f" Could not retrieve collection {home_collection_path}: {e}")
except Exception as e:
print(f"An error occurred during iRODS connection or operation: {e}")
print("Please ensure your iRODS server is running and credentials are correct.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'irods'
Attempting to import from the top-level 'irods' module, or the package was not installed correctly.
fixEnsure `python-irodsclient` is installed (`pip install python-irodsclient`). Imports should typically be from submodules like `from irods.session import iRODSSession`.
irods.exception.iRODSAuthError: [CAT_AUTHENTICATION_ERROR] user authentication error
Incorrect username, password, zone, or host details provided during session initialization, or issues with `irods_environment.json`.
fixVerify all connection parameters (host, port, zone, user, password) are correct. Check `~/.irods/irods_environment.json` if used, or ensure environment variables are set correctly.
AttributeError: 'iRODSSession' object has no attribute 'permissions'
In v2.0.0, the `permissions` attribute was renamed to `acls` for clarity and consistency with iRODS terminology.
fixUpdate your code to use `session.acls` instead of `session.permissions` when managing access control lists.
RuntimeError: unsupported Python version
The installed `python-irodsclient` version requires Python 3.9 or newer, but an older Python version is being used.
fixUpgrade your Python environment to version 3.9 or later. You might need to create a new virtual environment with a compatible Python version.
Upgrade
Version history
3.3.0latest on PyPI · released Mar 18, 2026
Audit
Dependencies
setuptoolsrequiredBuild-time and runtime utilities
json-streamrequiredJSON parsing utility
python-irodsclient-cffirequiredCFFI bindings for core iRODS communication