podman-py-5-8-0 - SKILL.md Agent Skill

name: podman-py-5-8-0 description: Python client library for Podman container engine providing programmatic access to containers, images, pods, networks, volumes, manifests, secrets, and quadlets via RESTful API. Use when building Python applications that require container orchestration, automation scripts, CI/CD integration, or container management without Docker dependency.

Podman Python SDK 5.8.0

Overview

PodmanPy is a Python3 library of bindings to the RESTful API of Podman. It provides a Docker-compatible interface for managing containers, images, networks, volumes, pods, manifests, secrets, and quadlets programmatically from Python. The package connects to a running Podman service via Unix socket, TCP, or SSH.

The API design mirrors the Docker SDK for Python, making migration straightforward. PodmanPy requires Python 3.9+ and depends on requests, urllib3, and tomli (for Python < 3.11).

When to Use

Automating container lifecycle operations from Python scripts
Building CI/CD pipelines that manage containers without Docker
Creating container orchestration tools with Podman as backend
Writing automation that needs pod support (not available in Docker)
Managing quadlet systemd unit files programmatically
Any scenario requiring programmatic access to Podman's REST API

Installation / Setup

Install from PyPI:

pip install podman

Optional progress bar support:

pip install "podman[progress_bar]"

Connecting to Podman Service

PodmanPy connects through a URL where the scheme determines the transport:

Unix socket (local): unix:///run/user/1000/podman/podman.sock or http+unix:///run/podman/podman.sock
SSH: ssh://user@host:22/run/podman/podman.sock?secure=True or http+ssh://user@host/path
TCP: tcp://hostname:port

The scheme aliases unix, ssh, and http+unix are accepted as shorthand.

Usage Examples

Basic client usage with context manager

from podman import PodmanClient

with PodmanClient(base_url="unix:///run/user/1000/podman/podman.sock") as client:
    if client.ping():
        print("Podman service is running")

Listing and managing containers

with PodmanClient() as client:
    for container in client.containers.list():
        container.reload()  # refresh status from sparse list data
        print(container.id, container.name, container.status)

Running a container

with PodmanClient() as client:
    container = client.containers.run(
        "alpine:latest",
        ["echo", "hello world"],
        detach=True,
        name="my-container"
    )
    print(container.logs())
    container.remove(force=True)

Working with images

with PodmanClient() as client:
    # Pull an image
    image = client.images.pull("alpine", tag="3.19")
    print(image.id, image.tags)

    # List images
    for img in client.images.list():
        print(img.id, img.tags)

    # Remove image
    image.remove(force=True)

Building images from Dockerfile

with PodmanClient() as client:
    image, logs = client.images.build(
        path="./my-app",
        dockerfile="Dockerfile",
        tag="my-app:latest"
    )
    print(f"Built image: {image.id}")

Core Concepts

PodmanClient — Main entry point, implements context manager protocol. Access resource managers via properties: containers, images, networks, volumes, pods, manifests, secrets, quadlets.
Manager pattern — Each resource type has a Manager (e.g. ContainersManager) providing list(), get(), exists(), create(), and remove() operations.
Resource objects — Individual entities (Container, Image, Network, etc.) expose properties and methods for inspection and lifecycle control. All inherit from PodmanResource with common id, short_id, reload().
Connection URL schemes — unix://, http+unix://, ssh://, http+ssh://, tcp:// determine transport. Default falls back to local Unix socket at $XDG_RUNTIME_DIR/podman/podman.sock.
Docker compatibility — API mirrors Docker SDK for Python. from_env() classmethod reads CONTAINER_HOST/DOCKER_HOST environment variables for connection configuration.
Swarm not supported — Podman does not support Swarm mode. Accessing .configs, .nodes, or .services raises NotImplementedError.

Advanced Topics

Container Operations: Lifecycle management, exec, logs, stats, file transfer → Container Operations

Image Management: Build, pull, push, save, load, tag, prune → Image Management

Networks and Volumes: Network creation, container connectivity, volume lifecycle → Networks and Volumes

Pods: Pod lifecycle, stats, multi-container grouping → Pods

Manifests, Secrets, Quadlets: Multi-arch manifests, secret management, systemd quadlet integration → Manifests, Secrets, and Quadlets

Configuration and Events: PodmanConfig, service connections, event streaming → Configuration and Events

Error Handling: Exception hierarchy, error classification → Error Handling