docker-pycreds: Python bindings for the Docker credentials store API

Warnings

• gotcha This library acts as a Python wrapper around external `docker-credential-<helper>` executables. It requires a suitable credential helper to be installed and available in your system's PATH (e.g., `docker-credential-secretservice` for Linux). Without these executables, the library cannot function.
  Fix: Install the appropriate Docker credential helper for your operating system and ensure it's accessible in your system's PATH. Refer to Docker's official documentation on credential helpers.
• deprecated The library has not been updated since November 2018 (version 0.4.0). While it's a dependency of the actively maintained `docker` (formerly `docker-py`) library, direct usage might encounter compatibility issues with newer Python versions (beyond 3.6) or recent changes in Docker's credential helper API.
  Fix: For core Docker interactions, rely on the `docker` SDK for Python which manages this dependency. If direct interaction is required, thoroughly test with your target Python and Docker environment. Be aware that issues might not be patched.
• gotcha There is another Python library named `pycreds` (pypi.org/project/pycreds) which is unrelated to Docker credentials. `docker-pycreds` is specifically for integrating with Docker's credential store.
  Fix: Ensure you `pip install docker-pycreds` and import `dockerpycreds` to use this library. Do not confuse it with `pycreds`.
• gotcha Operations like `store()`, `get()`, and `delete()` often interact with the operating system's credential store (e.g., keyring, secure vault). This can lead to system-level password prompts, especially for the 'secretservice' backend on Linux, which might cause hangs in non-interactive environments.
  Fix: When using `docker-pycreds` in automated scripts or non-interactive environments, ensure that the chosen credential helper backend is configured for non-interactive use, or consider using environment variables for credentials where appropriate and secure.

Install

• pip install docker-pycreds Install stable version from PyPI

Imports

• Store

  from dockerpycreds import Store

Quickstart

This quickstart demonstrates how to instantiate a credential store and use it to store and list Docker credentials. It assumes a `docker-credential` helper for your platform is installed and configured. Storing credentials might trigger a system-level prompt for keyring access depending on the backend.

import dockerpycreds
import os

# Configure the credential store backend. Common options include:
# 'secretservice' (Linux), 'osxkeychain' (macOS), 'wincred' (Windows)
# If you have a custom credential helper, use its name (e.g., 'ecr-login')
# Ensure the corresponding 'docker-credential-<backend>' executable is in your PATH.
store_backend = os.environ.get('DOCKER_CREDS_STORE_BACKEND', 'secretservice')
store = dockerpycreds.Store(store_backend)

# Define credentials from environment variables for security in examples
server_url = os.environ.get('DOCKER_SERVER_URL', 'https://index.docker.io/v1/')
username = os.environ.get('DOCKER_USERNAME', 'testuser')
secret = os.environ.get('DOCKER_SECRET', 'testpassword')

print(f"Attempting to store credentials for {username} on {server_url} using '{store_backend}'...")
try:
    store.store(
        server=server_url,
        username=username,
        secret=secret
    )
    print("Credentials stored successfully. Note: This might have prompted for system keyring access.")
except Exception as e:
    print(f"Failed to store credentials: {e}. Ensure the credential helper is correctly configured and accessible.")

print("\nListing all known Docker credential servers:")
try:
    creds_list = store.list()
    if creds_list:
        for server, user in creds_list.items():
            print(f"  Server: {server}, Username: {user}")
    else:
        print("  No credentials found.")
except Exception as e:
    print(f"Failed to list credentials: {e}. Listing may require user interaction or specific backend support.")

# Example of getting credentials (often requires explicit interaction with the helper)
# This is commented out as it frequently requires external CLI calls or user prompts
# which are hard to automate in a simple quickstart.
# try:
#     retrieved_username, retrieved_secret = store.get(server_url)
#     print(f"\nRetrieved credentials for {server_url}: Username: {retrieved_username}, Secret: {'*' * len(retrieved_secret)}")
# except Exception as e:
#     print(f"Failed to retrieve credentials: {e}. This often requires direct Docker CLI interaction or specific credential helper setup.")