Python DXF (Docker Registry Client)

12.1.1 · active · verified Thu Apr 16

python-dxf is a Python module and command-line tool for storing and retrieving data in a Docker v2 registry. It functions as a Docker registry v2 client, enabling tasks like transferring Docker images between registries, especially useful for disconnected environments. The library creates payloads directly from the registry, which can be faster than `docker save` and `docker load`, and can compute diffs to reduce transfer size. The current version is 12.1.1 and it appears to be actively maintained.

Common errors

```
Failed to connect: 'No such host is known'
```
cause The `DXF_HOST` environment variable is not set or points to an invalid/unreachable Docker registry host.

fix Ensure the `DXF_HOST` environment variable is set to the correct hostname or IP address of your Docker registry, or pass the correct host argument to the `Dxf` constructor.
```
Failed to connect or perform operation: Authentication Required
```
cause Incorrect or missing authentication credentials (username, password, or authorization token) for the Docker registry.

fix Set `DXF_USERNAME` and `DXF_PASSWORD` environment variables, or `DXF_AUTHORIZATION` for a raw token. Verify that the credentials are correct and have the necessary permissions for the desired operations (e.g., pull, push).

Warnings

gotcha The `python-dxf` library *does not* generate Docker container configurations. This means you cannot simply `docker pull` data that you store using this library directly without additional steps to create the necessary Docker image manifest and configuration.
Fix: Be aware of this limitation and plan to generate Docker image configurations separately if `docker pull` compatibility is required. This library is primarily for raw registry interaction (blobs, manifests).
gotcha Authentication to the Docker registry heavily relies on environment variables (`DXF_HOST`, `DXF_USERNAME`, `DXF_PASSWORD`, `DXF_INSECURE`, `DXF_AUTHORIZATION`, `DXF_AUTH_HOST`). Misconfiguration or omission of these can lead to authentication failures or incorrect registry connections.
Fix: Always ensure the necessary `DXF_*` environment variables are correctly set for your target registry, or pass the corresponding arguments directly to the `Dxf` constructor if the API supports it in your version. For production, consider using a secure secrets management system.

Install

pip install python-dxf Install latest version

Imports

Dxf
```
from dxf import Dxf
```
The primary class for interacting with a Docker registry.

Quickstart

This quickstart demonstrates how to initialize the `Dxf` client for a Docker registry, using environment variables for configuration. It shows the basic connection pattern. Actual registry operations (like listing repositories, pushing/pulling blobs or manifests) require specific API calls which might vary depending on the exact version and intended functionality. Ensure environment variables like `DXF_HOST`, `DXF_USERNAME`, and `DXF_PASSWORD` are set for authentication and host connection.

import os
from dxf import Dxf

# Configure registry connection via environment variables or direct arguments
# DXF_HOST, DXF_USERNAME, DXF_PASSWORD, DXF_INSECURE, etc.

host = os.environ.get('DXF_HOST', 'registry.example.com')
username = os.environ.get('DXF_USERNAME', '')
password = os.environ.get('DXF_PASSWORD', '')
insecure = os.environ.get('DXF_INSECURE', '0') == '1'

try:
    # Connect to the registry
    # In a real scenario, handle credentials securely (e.g., from a vault)
    client = Dxf(host, username=username, password=password, insecure=insecure)
    print(f"Connected to registry: {host}")

    # Example: List repositories (requires appropriate permissions)
    # NOTE: Dxf API might not directly expose 'list_repositories' in all versions,
    # this is a conceptual example based on its registry client nature.
    # Refer to the official library documentation for exact API calls.
    # if hasattr(client, 'list_repositories'): # Illustrative, actual method names vary
    #     repositories = client.list_repositories()
    #     print(f"Repositories: {repositories}")
    # else:
    #     print("Method to list repositories not found or not directly exposed by Dxf object.")

    # More likely usage involves specific image/layer operations, e.g.:
    # blob_digest = client.push_blob('my-repo/my-image', 'sha256:...')
    # manifest = client.get_manifest('my-repo/my-image', 'latest')
    print("Dxf client initialized. You can now perform registry operations.")

except Exception as e:
    print(f"Failed to connect or perform operation: {e}")

view raw JSON →