podman-con...er-runlabel(1) General Commands Manual podman-con...er-runlabel(1)
NAME
podman-container-runlabel - Execute a command as described by a con-
tainer-image label
SYNOPSIS
podman container runlabel [options] label image [arg...]
DESCRIPTION
podman container runlabel reads the specified label of the image and ex-
ecutes it as command on the host. If the label does not exist, Podman
exits with an error. Additional arguments are appended to the command.
Historically, container images describe the contents (e.g., layers) and
how a container runtime (e.g., crun(1) or runc(1)) executes the con-
tainer. For instance, an image may set the environment and the command
in its configuration. However, a container image cannot directly spec-
ify how a container engine such as Podman executes it. For instance, an
image configuration does not include information about log drivers,
namespaces, or which capabilities it needs to run correctly.
podman container runlabel addresses the limitation of container images
in a simple yet efficient way. Podman reads the contents of the label
and interpret it as a command that is executed on the host. This way an
image can describe exactly how it is executed by Podman. For instance,
a label with the content /usr/bin/podman run -d --pid=host --privileged
\${IMAGE} instructs the image to be executed in a detached, privileged
container that is using the PID namespace of the host. This lifts the
self-description of a container image from "what" to "how".
Note that the runlabel command is intended to be run in trusted environ-
ments exclusively. Using the command on untrusted images is not recom-
mended.
VARIABLES
The contents of a label may refer to the following variables which is
substituted while processing the label.
IMAGE The name of the image. When executing podman container runlabel
label fedora the IMAGE variable is replaced with fedora. Valid formats
are IMAGE, $IMAGE, ${IMAGE} and =IMAGE.
NAME As specified by the --name option. The format is identical to the
one of the IMAGE attribute.
PWD Will be replaced with the current working directory.
OPTIONS
--authfile=path
Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain-
ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win-
dows/macOS. The file is created by podman login. If the authorization
state is not found there, $HOME/.docker/config.json is checked, which is
set using docker login.
Note: There is also the option to override the default path of the au-
thentication file by setting the REGISTRY_AUTH_FILE environment vari-
able. This can be done with export REGISTRY_AUTH_FILE=path.
--cert-dir=path
Use certificates at path (*.crt, *.cert, *.key) to connect to the reg-
istry. (Default: /etc/containers/certs.d) For details, see containers-
certs.d(5). (This option is not available with the remote Podman
client, including Mac and Windows (excluding WSL2) machines)
--creds=[username[:password]]
The [username[:password]] to use to authenticate with the registry, if
required. If one or both values are not supplied, a command line prompt
appears and the value can be entered. The password is entered without
echo.
Note that the specified credentials are only used to authenticate
against target registries. They are not used for mirrors or when the
registry gets rewritten (see containers-registries.conf(5)); to authen-
ticate against those consider using a containers-auth.json(5) file.
--display
Display the label's value of the image having populated its environment
variables. The runlabel command is not executed if --display is speci-
fied.
--help, -h
Print usage statement
--name, -n=name
Use this name for creating content for the container. If not specified,
name defaults to the name of the image.
--quiet, -q
Suppress output information when pulling images
--replace
If a container exists with the current name, it is stopped, deleted and
a new container is created from this image.
--tls-verify
Require HTTPS and verify certificates when contacting registries (de-
fault: true). If explicitly set to true, TLS verification is used. If
set to false, TLS verification is not used. If not specified, TLS veri-
fication is used unless the target registry is listed as an insecure
registry in containers-registries.conf(5)
EXAMPLES
Execute the run label of an image called foobar.
$ podman container runlabel run foobar
Execute the install label of an image called foobar with additional ar-
guments.
$ podman container runlabel install foobar apples oranges
Display the contents of the run label of image foobar.
$ podman container runlabel --display run foobar
SEE ALSO
podman(1), crun(1), runc(8), containers-certs.d(5), containers-
auth.json(5), containers-registries.conf(5)
HISTORY
August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot
com)
September 2018, Originally compiled by Brent Baude (bbaude at redhat dot
com)
podman-con...er-runlabel(1)
Generated by dwww version 1.16 on Tue Dec 16 06:06:02 CET 2025.