Podman Python Client

Warnings

• breaking Major version `5.0.0` was released with a brief changelog, which typically implies underlying API changes and potential breaking changes in method signatures or data models. While not explicitly detailed in release notes, users upgrading from `4.x.x` should review their code for compatibility.
  Fix: Thoroughly test existing code after upgrading to `5.0.0` or higher. Consult the Podman-py GitHub repository's commit history or more detailed documentation (if available) for specific changes related to `5.0.0`.
• gotcha Connecting to the correct Podman socket or API URL can be challenging. Rootful Podman often uses `/run/podman/podman.sock`, while rootless Podman uses a user-specific path like `/run/user/<UID>/podman/podman.sock` (often determined by `XDG_RUNTIME_DIR`). If `PODMAN_HOST` environment variable is not set, `podman-py` attempts to infer the correct path. Explicitly setting `base_url` in `PodmanClient` constructor might be necessary for specific setups or remote connections.
  Fix: Set the `PODMAN_HOST` environment variable (e.g., `export PODMAN_HOST=unix:///run/user/1000/podman/podman.sock`) or explicitly pass `base_url` to `PodmanClient(base_url='unix:///path/to/socket')`.
• gotcha Version `5.4.0` had an issue with its `pyproject.toml` configuration, leading to 'submodules invisibility' which could cause `ModuleNotFoundError` for some submodules or classes within the `podman` package. This was fixed in `5.4.0.1`.
  Fix: Upgrade to `podman-py` version `5.4.0.1` or newer to resolve module import issues.
• gotcha Authentication for image pushes (e.g., `images.push()`) might have failed prior to version `5.1.0` due to incorrect encoding of the `X-Registry-auth` HTTP Header value. The library previously used standard Base64, but required URL-safe Base64 encoding.
  Fix: Upgrade to `podman-py` version `5.1.0` or newer to ensure correct `X-Registry-auth` header encoding for image registry operations.
• gotcha Ensure the `podman-py` client library version is reasonably compatible with your underlying Podman daemon version. Significant discrepancies can lead to unexpected behavior, missing features, or API mismatches, as the client's API models and calls are designed to match the daemon's capabilities.
  Fix: Keep your `podman-py` client library and Podman daemon versions relatively aligned. Refer to the `podman-py` documentation or release notes for specific compatibility information if you encounter issues.

Install

• pip install podman Install latest version

Imports

• PodmanClient
  wrong:

  import podman; client = podman.client.PodmanClient()

  correct:

  from podman import PodmanClient

  The primary client class is directly available under the top-level `podman` package.

Quickstart

This quickstart demonstrates how to initialize `PodmanClient` to connect to a running Podman daemon. By default, it tries to auto-detect the socket. It then prints system information and lists any running containers. This example is designed to work with both rootful and rootless Podman installations, assuming the default socket paths.

import podman
import os

# By default, PodmanClient attempts to connect to the Podman socket based on environment variables
# (e.g., PODMAN_HOST) or standard locations (e.g., /run/user/$UID/podman/podman.sock).
# You can also explicitly specify a base_url, e.g., for a remote Podman service or specific socket.

# Example using default connection (rootless or rootful Podman socket):
try:
    client = podman.PodmanClient()
    info = client.system.info()
    print(f"Connected to Podman. Version: {info['Version']}")
    
    # Example: List containers
    print("\nRunning containers:")
    for container in client.containers.list():
        print(f"  - {container.name} ({container.id[:12]})")

except Exception as e:
    print(f"Error connecting to Podman or executing command: {e}")
    print("Ensure Podman is running and accessible (e.g., 'systemctl --user start podman.socket' for rootless).")

# Example with explicit base_url (uncomment to test specific connections)
# rootless_socket = os.environ.get('XDG_RUNTIME_DIR', '/run/user/1000') + '/podman/podman.sock'
# try:
#     client_socket = podman.PodmanClient(base_url=f'unix://{rootless_socket}')
#     info_socket = client_socket.system.info()
#     print(f"\nConnected via explicit socket. Version: {info_socket['Version']}")
# except Exception as e:
#     print(f"Error connecting via explicit socket: {e}")