{"id":6774,"library":"podman","title":"Podman Python Client","description":"Podman-py provides Python bindings for the Podman RESTful API, enabling programmatic interaction with Podman containers, images, networks, and pods. As of version 5.8.0, it offers a comprehensive client for managing Podman resources. The project is actively maintained with frequent minor releases, typically on a monthly or bi-monthly cadence, introducing new features and bug fixes.","status":"active","version":"5.8.0","language":"en","source_language":"en","source_url":"https://github.com/containers/podman-py","tags":["container","podman","docker-compatible","cli","rest-api","orchestration"],"install":[{"cmd":"pip install podman","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for HTTP communication with the Podman REST API.","package":"httpx","optional":false},{"reason":"Used for data validation and parsing of API models.","package":"pydantic","optional":false}],"imports":[{"note":"The primary client class is directly available under the top-level `podman` package.","wrong":"import podman; client = podman.client.PodmanClient()","symbol":"PodmanClient","correct":"from podman import PodmanClient"}],"quickstart":{"code":"import podman\nimport os\n\n# By default, PodmanClient attempts to connect to the Podman socket based on environment variables\n# (e.g., PODMAN_HOST) or standard locations (e.g., /run/user/$UID/podman/podman.sock).\n# You can also explicitly specify a base_url, e.g., for a remote Podman service or specific socket.\n\n# Example using default connection (rootless or rootful Podman socket):\ntry:\n    client = podman.PodmanClient()\n    info = client.system.info()\n    print(f\"Connected to Podman. Version: {info['Version']}\")\n    \n    # Example: List containers\n    print(\"\\nRunning containers:\")\n    for container in client.containers.list():\n        print(f\"  - {container.name} ({container.id[:12]})\")\n\nexcept Exception as e:\n    print(f\"Error connecting to Podman or executing command: {e}\")\n    print(\"Ensure Podman is running and accessible (e.g., 'systemctl --user start podman.socket' for rootless).\")\n\n# Example with explicit base_url (uncomment to test specific connections)\n# rootless_socket = os.environ.get('XDG_RUNTIME_DIR', '/run/user/1000') + '/podman/podman.sock'\n# try:\n#     client_socket = podman.PodmanClient(base_url=f'unix://{rootless_socket}')\n#     info_socket = client_socket.system.info()\n#     print(f\"\\nConnected via explicit socket. Version: {info_socket['Version']}\")\n# except Exception as e:\n#     print(f\"Error connecting via explicit socket: {e}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<5.0.0"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `podman-py` version `5.4.0.1` or newer to resolve module import issues.","message":"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`.","severity":"gotcha","affected_versions":"5.4.0"},{"fix":"Upgrade to `podman-py` version `5.1.0` or newer to ensure correct `X-Registry-auth` header encoding for image registry operations.","message":"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.","severity":"gotcha","affected_versions":"<5.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}