Registry / devops / podman

podman

JSON →
library5.8.0pypypi✓ verified 87d ago

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.

pip install podman
INSTALL
IMPORT
SIG · PODMAN
P
podman
devopspythonv5.8.0
Install
2.2s avg
Import
712ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.8.0 · 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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.752s · 22MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.672s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PodmanClient
from podman import PodmanClient
import podman; client = podman.client.PodmanClient()
The primary client class is directly available under the top-level `podman` package.

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}")
podman --version
Debug
Known issues
breakingMajor 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`.
affects: <5.0.0
gotchaConnecting 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')`.
affects: All versions
gotchaVersion `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.
affects: 5.4.0
gotchaAuthentication 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.
affects: <5.1.0
gotchaEnsure 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'podman'
The 'podman' Python package is not installed in the active Python environment or the Python interpreter cannot find it in its search path. This often happens in virtual environments, Jupyter notebooks, or specific build systems like Yocto if dependencies are not correctly managed for the target environment.
fix
Ensure `podman` is installed in your current environment using `pip install podman`. If in a Jupyter notebook, use `%pip install podman`. If using a system like Yocto, verify the recipe correctly installs `python3-podman`.
BrokenPipeError: [Errno 32] Broken pipe
This error typically indicates that the connection to the Podman service was unexpectedly closed or could not be established. This can happen if the Podman service (daemon) is not running, the Unix socket path is incorrect, or there are permission issues accessing the socket.
fix
Verify that the Podman service is running (e.g., `systemctl --user status podman.service` for rootless or `systemctl status podman.service` for rootful). Ensure the `PODMAN_HOST` environment variable is correctly set, or explicitly pass the correct `base_url` (e.g., `unix:///run/user/{uid}/podman/podman.sock` for rootless) to `PodmanClient`. Check file permissions on the socket.
ModuleNotFoundError: No module named 'rich'
The `rich` package, which is an optional dependency for `podman-py` (often used for progress bars or rich output), is missing. This can occur if `podman-py` was installed without its optional dependencies, or if the environment's `pip` does not automatically resolve all transitive dependencies.
fix
Install the missing dependency using `pip install rich`.
podman.errors.ImageNotFound: No such image
This error occurs when the `podman-py` client attempts an operation on a container image that does not exist in the Podman service's image store. This could be due to a typo in the image name, the image not being pulled, or incorrect tagging.
fix
Verify the image name is correct and present locally using `podman images`. If the image is missing, pull it first using `client.images.pull('image_name')` before attempting to create or run a container from it.
podman.errors.APIError: 400 Bad Request
This generic API error indicates that the Podman service received a request that it considered malformed or invalid, often due to incorrect parameters or an unsupported operation for the current state.
fix
Review the parameters passed to the `podman-py` method that caused the error. Consult the `podman-py` documentation for the specific method to ensure all arguments are correct and in the expected format. Check for common issues like malformed YAML if using a higher-level tool or incorrect resource IDs.
Upgrade
Version history
5.8.0latest on PyPI · released Mar 25, 2026
Audit
Dependencies
httpxrequiredUsed for HTTP communication with the Podman REST API.
pydanticrequiredUsed for data validation and parsing of API models.
Agent activity
18 hits · last 30 days
node
18
Resources
podman — pip install podman · libregistry