Model and Manager for Container resources.

class Container(attrs: Mapping[str, Any] | None = None, client: APIClient | None = None, collection: Manager | None = None)[source]

Bases: PodmanResource

Details and configuration for a container managed by the Podman service.

Initialize base class for PodmanResource’s.

  • attrs – Mapping of attributes for resource from Podman service.

  • client – Configured connection to a Podman service.

  • collection – Manager of this category of resource, named collection for compatibility

attach(**kwargs) str | Iterator[str][source]

Attach to container’s tty.

Keyword Arguments:
  • stdout (bool) – Include stdout. Default: True

  • stderr (bool) – Include stderr. Default: True

  • stream (bool) – Return iterator of string(s) vs single string. Default: False

  • logs (bool) – Include previous container output. Default: False


NotImplementedError – method not implemented.


Not Implemented.


NotImplementedError – method not implemented.

commit(repository: str = None, tag: str = None, **kwargs) Image[source]

Save container to given repository.

  • repository – Where to save Image

  • tag – Tag to push with Image

Keyword Arguments:
  • author (str) – Name of commit author

  • changes (List[str]) – Instructions to apply during commit

  • comment (str) – Commit message to include with Image, overrides keyword message

  • conf (dict[str, Any]) – Ignored.

  • format (str) – Format of the image manifest and metadata

  • message (str) – Commit message to include with Image

  • pause (bool) – Pause the container before committing it

diff() List[Dict[str, int]][source]

Report changes of a container’s filesystem.


APIError – when service reports an error

exec_run(cmd: str | List[str], stdout: bool = True, stderr: bool = True, stdin: bool = False, tty: bool = False, privileged: bool = False, user=None, detach: bool = False, stream: bool = False, socket: bool = False, environment: Mapping[str, str] | List[str] = None, workdir: str = None, demux: bool = False) Tuple[int | None, Iterator[bytes] | Any | Tuple[bytes, bytes]][source]

Run given command inside container and return results.

  • cmd – Command to be executed

  • stdout – Attach to stdout. Default: True

  • stderr – Attach to stderr. Default: True

  • stdin – Attach to stdin. Default: False

  • tty – Allocate a pseudo-TTY. Default: False

  • privileged – Run as privileged.

  • user – User to execute command as. Default: root

  • detach – If true, detach from the exec command. Default: False

  • stream – Stream response data. Default: False

  • socket – Return the connection socket to allow custom read/write operations. Default: False

  • environment – A dictionary or a List[str] in the following format [“PASSWORD=xxx”] or {“PASSWORD”: “xxx”}.

  • workdir – Path to working directory for this exec session

  • demux – Return stdout and stderr separately


First item is the command response code Second item is the requests response content

  • NotImplementedError – method not implemented.

  • APIError – when service reports error

export(chunk_size: int = 2097152) Iterator[bytes][source]

Download container’s filesystem contents as a tar archive.


chunk_size – <= number of bytes to return for each iteration of the generator.


tarball in size/chunk_size chunks

  • NotFound – when container has been removed from service

  • APIError – when service reports an error

get_archive(path: str, chunk_size: int = 2097152) Tuple[Iterable, Dict[str, Any]][source]

Download a file or folder from the container’s filesystem.

  • path – Path to file or folder.

  • chunk_size – <= number of bytes to return for each iteration of the generator.


First item is a raw tar data stream. Second item is a dict containing os.stat() information on the specified path.

inspect() Dict[source]

Inspect a container.


APIError – when service reports an error

kill(signal: str | int | None = None) None[source]

Send signal to container.


APIError – when service reports an error

logs(**kwargs) bytes | Iterator[bytes][source]

Get logs from the container.

Keyword Arguments:
  • stdout (bool) – Include stdout. Default: True

  • stderr (bool) – Include stderr. Default: True

  • stream (bool) – Return generator of strings as the response. Default: False

  • timestamps (bool) – Show timestamps in output. Default: False

  • tail (Union[str, int]) – Output specified number of lines at the end of logs. Integer representing the number of lines to display, or the string all. Default: all

  • since (Union[datetime, int]) – Show logs since a given datetime or integer epoch (in seconds)

  • follow (bool) – Follow log output. Default: False

  • until (Union[datetime, int]) – Show logs that occurred before the given datetime or integer epoch (in seconds)

pause() None[source]

Pause processes within the container.

put_archive(path: str, data: bytes = None) bool[source]

Upload tar archive containing a file or folder to be written into container.

  • path – File to write data into

  • data – Contents to write to file, when None path will be read on client to build tarfile.


True when successful


APIError – when server reports error

reload() None

Refresh this object’s data from the service.

remove(**kwargs) None[source]

Delete container.

Keyword Arguments:
  • v (bool) – Delete associated volumes as well.

  • link (bool) – Ignored.

  • force (bool) – Kill a running container before deleting.

rename(name: str) None[source]

Rename container.

Container updated in-situ to avoid reload().


name – New name for container.

resize(height: int = None, width: int = None) None[source]

Resize the tty session.

  • height – New height of tty session.

  • width – New width of tty session.

restart(**kwargs) None[source]

Restart processes in container.

Keyword Arguments:

timeout (int) – Seconds to wait for container to stop before killing container.

start(**kwargs) None[source]

Start processes in container.

Keyword Arguments:

detach_keys – Override the key sequence for detaching a container (Podman only)

stats(**kwargs) bytes | Dict[str, Any] | Iterator[bytes] | Iterator[Dict[str, Any]][source]

Return statistics for container.

Keyword Arguments:
  • decode (bool) – If True and stream is True, stream will be decoded into dict’s. Default: False.

  • stream (bool) – Stream statistics until cancelled. Default: True.


APIError – when service reports an error

stop(**kwargs) None[source]

Stop container.

Keyword Arguments:
  • all (bool) – When True, stop all containers. Default: False (Podman only)

  • ignore (bool) – When True, ignore error if container already stopped (Podman only)

  • timeout (int) – Number of seconds to wait on container to stop before killing it.

top(**kwargs) Iterator[Dict[str, Any]] | Dict[str, Any][source]

Report on running processes in the container.

Keyword Arguments:
  • ps_args (str) – When given, arguments will be passed to ps

  • stream (bool) – When True, repeatedly return results. Default: False

  • NotFound – when the container no longer exists

  • APIError – when the service reports an error

unpause() None[source]

Unpause processes in container.


Update resource configuration of the containers.


NotImplementedError – Podman service unsupported operation.

wait(**kwargs) int[source]

Block until the container enters given state.

Keyword Arguments:
  • condition (Union[str, List[str]]) – Container state on which to release. One or more of: “configured”, “created”, “running”, “stopped”, “paused”, “exited”, “removing”, “stopping”.

  • interval (int) – Time interval to wait before polling for completion.


“Error” key has a dictionary value with the key “Message”.

  • NotFound – when Container not found

  • ReadTimeoutError – when timeout is exceeded

  • APIError – when service returns an error

property id

Returns the identifier for the object.



property image

Returns Image object used to create Container.



property labels

Returns labels associated with container.


dict[str, str]

property name

Returns container’s name.



property ports

Return ports exposed by container.


dict[str, int]

property short_id

Returns truncated identifier. ‘sha256’ preserved when included in the id.

No attempt is made to ensure the returned value is semantically meaningful for all resources.



property status

Returns status of container.


Literal[“running”, “stopped”, “exited”, “unknown”]