Install & Compatibility
Where this runs
tested against v0.2.43 · 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.552s · 58.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.2s · import 0.521s · 58MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OrasClient
✓ from oras.client import OrasClient
The primary client for interacting with OCI registries.
ManifestConfig
✓ from oras.oci import ManifestConfig
Used for creating OCI manifest configuration objects.
This quickstart demonstrates how to initialize an `OrasClient`, log in (if necessary), and then push and pull a simple artifact to/from an OCI-compliant registry. It uses environment variables for registry hostname, username, and password for flexibility, falling back to a local insecure registry setup for ease of testing.
import os
from oras.client import OrasClient
# Prepare a dummy file to push
with open('artifact.txt', 'w') as f:
f.write('Hello, ORAS!')
registry_hostname = os.environ.get('ORAS_REGISTRY_HOSTNAME', 'localhost:5000')
repository_target = f"{registry_hostname}/my/artifact:v1"
username = os.environ.get('ORAS_USERNAME', '')
password = os.environ.get('ORAS_PASSWORD', '')
client = OrasClient(hostname=registry_hostname, insecure=True) # Use insecure=True for local registries without TLS
if username and password:
print(f"Attempting to login to {registry_hostname}...")
try:
client.login(username=username, password=password)
print("Login successful.")
except Exception as e:
print(f"Login failed: {e}")
# Depending on local setup, login might not be strictly necessary for insecure local registries
print(f"Pushing artifact to {repository_target}...")
try:
push_response = client.push(files=["artifact.txt"], target=repository_target)
print(f"Push successful: {push_response}")
except Exception as e:
print(f"Push failed: {e}")
print("Ensure a registry is running at and accessible from '" + registry_hostname + "'. For example: 'docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/oras-project/registry:latest'")
# Clean up after push if successful
# os.remove('artifact.txt') # Uncomment to clean up
# For pulling, create a new directory to avoid conflicts if artifact.txt already exists
pull_dir = './pulled_artifacts'
os.makedirs(pull_dir, exist_ok=True)
print(f"Pulling artifact from {repository_target} into {pull_dir}...")
try:
# Pulls into the current working directory by default, unless oras.utils.workdir is used
# For this example, we'll let it pull to current dir and specify path for clarity
pulled_files = client.pull(target=repository_target, output_dir=pull_dir)
print(f"Pull successful. Files: {pulled_files}")
# Verify content if needed
# with open(os.path.join(pull_dir, 'artifact.txt'), 'r') as f:
# print(f.read())
except Exception as e:
print(f"Pull failed: {e}")
# Cleanup pulled files
# import shutil
# shutil.rmtree(pull_dir)
# os.remove('artifact.txt') # If not removed after push
oras --version
Debug
Known issues
breakingAWS ECR authentication support (`oras[ecr]`) was moved to an optional extra. If you were previously relying on ECR authentication without explicitly installing `oras[ecr]`, your setup will break.fixEnsure you install the `ecr` extra: `pip install oras[ecr]`.
affects: 0.2.35 and earlier
breakingPython 3.7+ compatibility was fixed, specifically regarding the use of union syntax (e.g., `list | None`). If you are using Python 3.7 or older, or if your environment relied on previous (potentially broken) behavior, this might affect you.fixUpgrade to `oras>=0.2.39` or ensure your Python environment is 3.8+ if you encounter syntax errors related to type hints.
affects: 0.2.38 and earlier
gotchaThe authentication priority for various credential sources (AWS-native, docker login, credHelpers, credsStore) has been explicitly fixed and re-ordered. If your environment relies on a specific order of credential resolution, this change might alter how your client authenticates.fixReview your authentication setup and test with `oras>=0.2.36` to ensure credentials are resolved as expected. Debug authentication issues using the client's debug logs.
affects: 0.2.35 and earlier
gotchaThere have been multiple fixes related to how Docker's `credsStore` and `credHelpers` binaries are located and used for authentication. Users relying on these Docker credential helpers might experience intermittent authentication failures or incorrect credential resolution.fixEnsure you are on the latest `oras` version to benefit from `credsStore`/`credHelpers` bug fixes. Verify your Docker configuration (`~/.docker/config.json`) and the availability of helper binaries.
affects: Prior to 0.2.40 (and 0.2.37, 0.2.34)
gotchaAn open issue indicates potential data loss where `oras-py` strips paths to basename during pull operations, leading to filename collisions if multiple artifacts share the same basename. This could result in one artifact overwriting another upon pulling.fixWhen pulling, consider using unique output directories or carefully inspect the pulled files if you suspect filename collisions. Monitor the GitHub issues for a resolution.
affects: All versions up to 0.2.42 (as of April 2026)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'oras'
The 'oras' Python package is not installed in the current Python environment or the environment where the script is being executed.
fixInstall the oras library using pip: `pip install oras`
Authentication failed.
The ORAS client failed to authenticate with the OCI registry due to incorrect credentials (username/password), missing authentication tokens, or an improperly configured authentication backend.
fixEnsure that the `ORAS_USERNAME` and `ORAS_PASSWORD` environment variables are set correctly, or provide valid credentials programmatically when initializing the `oras.provider.Registry` client. For a local registry without auth, ensure no authentication is attempted.
AttributeError: 'TokenAuth' object has no attribute 'prefix'
This error typically occurs in older versions of the `oras` Python SDK (e.g., prior to version 0.2.22) where the internal `TokenAuth` class was missing a required attribute, often surfacing when interacting with private OCI registries that require token-based authentication.
fixUpgrade the `oras` Python SDK to the latest stable version: `pip install --upgrade oras`.
TypeError: stat: path should be string, bytes, os.PathLike or integer, not list
This `TypeError` occurs when a function in the `oras` Python SDK expects a single path (string, bytes, or PathLike object) for arguments like `config_path` but receives a list of paths instead. This can happen in older SDK versions or due to incorrect argument handling.
fixEnsure that arguments expecting a single path (e.g., `config_path` in `pull` or `push` operations) are provided as a single string, `bytes`, `os.PathLike` object, or an integer file descriptor, not a list. If multiple configurations are needed, review the `oras` documentation for handling multiple configuration sources. Upgrading to the latest SDK version might also provide improved type handling or clearer error messages.
Upgrade
Version history
0.2.43latest on PyPI · released Aug 8, 2026
Audit
Dependencies
requestsrequiredUsed for HTTP communication with registries.
jsonschemarequiredUsed for OCI schema validation.
ecroptionalRequired for AWS ECR specific authentication mechanisms.