名称

podman - 用于 pod、容器和镜像的简单管理工具

概要

podman [选项] 命令

描述

Podman（Pod 管理器）是一个功能齐全的容器引擎，是一个简单的无守护进程工具。Podman 提供了一个与 Docker-CLI 相似的命令行，简化了从其他容器引擎的过渡，并允许管理 pod、容器和镜像。简单地说：alias docker=podman。大多数 Podman 命令可以作为普通用户运行，无需额外的权限。

Podman 在内部使用 Buildah(1) 来创建容器镜像。这两个工具共享镜像（而不是容器）存储，因此每个工具都可以使用或操作由另一个工具创建的镜像（但不能操作容器）。

标志的默认设置在 containers.conf 中定义。远程连接的大多数设置使用服务器的 containers.conf，除非手册页中有说明。

podman [全局选项]

全局选项

--cgroup-manager=管理器

要用于容器 cgroup 的 CGroup 管理器。支持的值为 cgroupfs 或 systemd。默认值为 systemd，除非在 containers.conf 文件中被覆盖。

注意：设置此标志可能会导致某些命令在针对之前由其他 CGroup 管理器类型创建的容器调用时中断。注意：在使用 CGroups 版本 V1 时，CGroup 管理器在无根模式下不受支持。

--config

配置文件的位置。主要用于 Docker 兼容性，仅支持配置文件的认证部分。

--conmon

conmon 二进制文件路径（默认路径在 containers.conf 中配置）

--connection, -c

用于远程 podman 的连接，包括 Mac 和 Windows（不包括 WSL2）机器（默认连接在 containers.conf 中配置）。设置此选项会将 --remote 选项切换为 true。远程连接使用本地 containers.conf 作为默认值。

--events-backend=类型

用于存储事件的后端。允许的值为 file、journald 和 none。当指定 file 时，事件将存储在 <tmpdir>/events/events.log 下（参见下面的 --tmpdir）。

--help, -h

打印使用说明

--hooks-dir=路径

路径中的每个 *.json 文件都为 Podman 容器配置一个钩子。有关 JSON 文件语法和钩子注入语义的更多详细信息，请参见 oci-hooks(5)。Podman 和 libpod 当前支持 1.0.0 和 0.1.0 钩子模式，尽管 0.1.0 模式已弃用。

此选项可以多次设置；来自后面选项的路径具有更高的优先级（oci-hooks(5) 讨论目录优先级）。

对于注释条件，libpod 使用在生成的 OCI 配置中设置的任何注释。

对于绑定挂载条件，只考虑调用者通过 --volume 显式请求的挂载。libpod 默认插入的绑定挂载（例如 /dev/shm）不予考虑。

如果对根调用者未设置 --hooks-dir，Podman 和 libpod 当前默认设置为 /usr/share/containers/oci/hooks.d 和 /etc/containers/oci/hooks.d，按优先级递增的顺序排列。使用这些默认值已被弃用。迁移到显式设置 --hooks-dir。

Podman 和 libpod 当前支持一个额外的 precreate 状态，它在运行时的 create 操作之前调用。与其他阶段不同（它们在标准输入中接收容器状态），precreate 钩子在标准输入中接收建议的运行时配置。它们可以根据需要更改该配置，并将更改后的形式写入它们的标准输出。

警告：precreate 钩子允许进行强大的更改，例如在运行时配置中添加额外的挂载。这种能力也使得破坏事物变得容易。在报告 libpod 错误之前，请尝试禁用 precreate 钩子运行一个容器，以查看问题是否是由其中一个钩子引起的。

--identity=路径

ssh 身份文件路径。如果身份文件已加密，podman 会提示用户输入密码。如果未提供身份文件，并且未给出用户，podman 默认使用运行 podman 命令的用户。Podman 会提示输入远程服务器上的登录密码。

身份值解析优先级

• 命令行值

• 环境变量 CONTAINER_SSHKEY，如果找到 CONTAINER_HOST

• containers.conf 远程连接使用本地 containers.conf 作为默认值。

--imagestore=路径

镜像存储路径，其中存储镜像。默认情况下，存储库将所有镜像存储在 graphroot 中，但如果提供了一个镜像存储，那么存储库将把新拉取的镜像存储在提供的镜像存储中，并继续使用 graphroot 来存储其他所有内容。如果用户正在使用 overlay 驱动程序，那么已经成为 graphroot 一部分的镜像仍然可以访问。

这将覆盖 containers-storage.conf(5) 中的 imagestore 选项，有关更多详细信息，请参阅 containers-storage.conf(5)。

--log-level=级别

记录指定级别及以上级别的日志消息：debug、info、warn、error、fatal 或 panic（默认值：warn）

--module=路径

加载指定的 containers.conf(5) 模块。可以是绝对路径或相对路径。有关详细信息，请参阅 containers.conf(5)。

此标志在远程客户端（包括 Mac 和 Windows（不包括 WSL2）机器）上不受支持。此外要注意，该标志是根级标志，必须在任何 Podman 子命令之前指定。

--network-cmd-path=路径

用于设置 slirp4netns 网络的 slirp4netns(1) 命令二进制文件路径。如果使用 “”，那么该二进制文件将首先使用 containers.conf 中的 helper_binaries_dir 选项进行搜索，然后使用 $PATH 环境变量进行搜索。注意：此选项已弃用，将在 Podman 6.0 中删除。改用 containers.conf 中的 helper_binaries_dir 选项。

--network-config-dir=目录

网络配置文件所在的目录路径。对于 netavark 后端，根目录使用 “/etc/containers/networks”，无根目录使用 “$graphroot/networks”。对于 CNI 后端，根目录的默认值为 “/etc/cni/net.d”，无根目录的默认值为 “$HOME/.config/cni/net.d”。CNI 已弃用，将在下一个主要 Podman 版本 5.0 中删除，以支持 Netavark。

--out=路径

将 podman 的输出重定向到指定的路径，而不影响容器输出或其日志。此参数可用于将 podman 的任何命令的输出直接捕获到文件中，并通过指定 /dev/null 作为路径来抑制 podman 的输出。要显式禁用容器日志记录，应使用 --log-driver 选项。

--remote, -r

如果为 true，则对 Podman 服务的访问为远程。默认值为 false。设置可以在 containers.conf 文件中修改。如果设置了 CONTAINER_HOST 环境变量，--remote 选项默认为 true。

--root=值

存储根目录，其中存储数据（包括镜像）（对于 UID 0，默认值为 “/var/lib/containers/storage”，对于其他用户，默认值为 “$HOME/.local/share/containers/storage”）。默认根目录在 containers-storage.conf(5) 中配置。

覆盖此选项会导致忽略 containers-storage.conf(5) 中的 storage-opt 设置。用户必须通过 --storage-opt 标志指定其他选项。

--runroot=值

存储状态目录，其中存储所有状态信息（对于 UID 0，默认值为 “/run/containers/storage”，对于其他用户，默认值为 “/run/user/$UID/run”）。默认状态目录在 containers-storage.conf(5) 中配置。

--runtime=值

OCI 运行时的名称，如 containers.conf 中所指定，或用于运行容器的与 OCI 兼容的二进制文件的绝对路径。

--runtime-flag=标志

为容器运行时添加全局标志。要列出支持的标志，请查阅所选容器运行时的联机帮助页（runc 是默认运行时，要查阅的联机帮助页为 runc(8)。当机器配置为 cgroup V2 时，默认运行时为 crun，要查阅的联机帮助页为 crun(8)）。

注意：不要将前导 -- 传递给标志。要将 runc 标志 --log-format json 传递给 podman build，可以提供的选项为 --runtime-flag log-format=json。

--ssh=值

此选项允许用户更改 ssh 模式，这意味着，与其使用默认的 golang 模式，不如改为使用 --ssh=native 来使用已安装的 ssh 二进制文件和 containers.conf 中声明的配置文件。

--storage-driver=value

存储驱动程序。UID 0 的默认存储驱动程序在 containers-storage.conf(5) 中配置（在无根模式下），当 fuse-overlayfs 不可用时，非 root 用户的默认存储驱动程序为 vfs。 STORAGE_DRIVER 环境变量会覆盖默认值。 指定的 --storage-driver 会覆盖所有设置。

覆盖此选项会导致忽略 containers-storage.conf(5) 中的 storage-opt 设置。用户必须通过 --storage-opt 标志指定其他选项。

--storage-opt=value

指定存储驱动程序选项。默认存储驱动程序选项在 containers-storage.conf(5) 中配置。 STORAGE_OPTS 环境变量会覆盖默认值。指定的 --storage-opt 会覆盖所有设置。指定 --storage-opt=”” 表示不使用任何存储选项。

--syslog

除了控制台之外，还将日志信息输出到 syslog（默认值为 false）。

在远程客户端（包括 Mac 和 Windows（不包括 WSL2）机器）上，日志将被定向到文件 $HOME/.config/containers/podman.log。

--tmpdir=path

libpod 运行时内容的临时目录路径。默认情况下，无根模式下为 $XDG_RUNTIME_DIR/libpod/tmp，有根模式下为 /run/libpod/tmp。

注意，--tmpdir 不用于下载镜像的临时存储。使用环境变量 TMPDIR 来更改下载容器镜像的临时存储位置。Podman 默认使用 /var/tmp。

--transient-store

启用全局瞬态存储模式，所有容器元数据都存储在非持久性介质上（即在 --runroot 指定的位置）。此模式允许更快地启动容器，并保证在启动时恢复干净状态，以防意外关机或其他问题。但是，它与容器在重启之间持久存在的传统模型不兼容。

此选项的默认值在 containers-storage.conf(5) 中配置。

--url=value

访问 Podman 服务的 URL（默认值来自 containers.conf，无根模式下为 unix:///run/user/$UID/podman/podman.sock，有根模式下为 unix:///run/podman/podman.sock）。设置此选项会将 --remote 选项切换为 true。

• CONTAINER_HOST 的格式为 <schema>://[<user[:<password>]@]<host>[:<port>][<path>]

详细信息

• schema 为以下之一

  • ssh（默认值）：在指定的 host 和 port 上的本地 unix(7) 套接字，可以通过 SSH 访问

  • tcp：与指定的 host 和 port 之间的未加密、未经身份验证的 TCP 连接

  • unix：位于指定 path 的本地 unix(7) 套接字，或用户的默认路径

• user 默认值为 root 或当前运行的用户（仅限 ssh）

• password 没有默认值（仅限 ssh）

• host 必须提供，并且是托管 Podman 服务的机器的 IP 或名称（ssh 和 tcp）

• port 默认值为 22（ssh 和 tcp）

• path 默认值为 /run/podman/podman.sock 或 /run/user/$UID/podman/podman.sock（如果以无根模式运行）（unix），或者必须显式指定（ssh）

URL 值解析优先级

• 命令行值

• 环境变量 CONTAINER_HOST

• containers.conf 中的 engine.service_destinations 表，不包括 /usr/share/containers 目录

• unix:///run/podman/podman.sock

远程连接使用本地 containers.conf 作为默认值。

一些有效格式的示例 URL 值

• unix:///run/podman/podman.sock

• unix:///run/user/$UID/podman/podman.sock

• ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock

• ssh://root@localhost:22/run/podman/podman.sock

• tcp://127.0.0.1:34451

• tcp://127.0.0.1:34451

--version, -v

打印版本

--volumepath=value

存储内置卷信息的卷目录（默认值：UID 0 为“/var/lib/containers/storage/volumes”，其他用户为“$HOME/.local/share/containers/storage/volumes”）。默认卷路径可以在 containers.conf 中覆盖。

环境变量

Podman 可以从 containers.conf 中 [engine] 表的 env 设置环境变量。这些变量可以通过在 podman 命令之前传递环境变量来覆盖。

CONTAINERS_CONF

设置 containers.conf 文件的默认位置

CONTAINERS_REGISTRIES_CONF

设置 registries.conf 文件的默认位置。

CONTAINERS_STORAGE_CONF

设置 storage.conf 文件的默认位置。

CONTAINER_CONNECTION

覆盖默认的 --connection 值以访问 Podman 服务。自动启用 --remote 选项。

CONTAINER_HOST

设置默认的 --url 值以访问 Podman 服务。自动启用 --remote 选项。

CONTAINER_SSHKEY

设置默认的 --identity 路径到用于访问 Podman 服务的 ssh 密钥文件的值。

PODMAN_CONNECTIONS_CONF

使用 podman system connection add 和 podman farm add 创建的系统连接和农场存储的文件路径，默认情况下使用 ~/.config/containers/podman-connections.json。

STORAGE_DRIVER

设置默认的 --storage-driver 值。

STORAGE_OPTS

设置默认的 --storage-opt 值。

TMPDIR

设置下载容器镜像的临时存储位置。Podman 默认使用 /var/tmp。

XDG_CONFIG_HOME

在无根模式下，配置文件从 XDG_CONFIG_HOME 读取（如果指定），否则从用户主目录下的 $HOME/.config/containers 读取。

XDG_DATA_HOME

在无根模式下，镜像被拉取到 XDG_DATA_HOME（如果指定），否则被拉取到用户主目录下的 $HOME/.local/share/containers/storage。

XDG_RUNTIME_DIR

在无根模式下，临时配置数据存储在 ${XDG_RUNTIME_DIR}/containers 中。

远程访问

Podman 命令可以使用 --remote 标志与远程服务一起使用。可以使用本地 unix 域套接字、ssh 或直接连接到 tcp 套接字来建立连接。在指定 podman --remote 标志时，仅使用全局选项 --url、--identity、--log-level、--connection。

连接信息也可以使用 containers.conf 文件进行管理。

退出代码

来自 podman 的退出代码提供有关容器无法运行或退出原因的信息。当 podman 命令以非零代码退出时，退出代码遵循 chroot 标准，请参见下文

125 错误与 podman 本身 有关

$ podman run --foo busybox; echo $?
Error: unknown flag: --foo
125

126 执行 容器命令，并且 命令 无法调用

$ podman run busybox /etc; echo $?
Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
126

127 执行 容器命令，并且 命令 无法找到

$ podman run busybox foo; echo $?
Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
127

退出代码 否则，podman 返回 容器命令 的退出代码

$ podman run busybox /bin/sh -c 'exit 3'; echo $?
3

命令

命令	描述
podman-attach(1)	附加到正在运行的容器。
podman-auto-update(1)	根据容器的自动更新策略自动更新容器
podman-build(1)	使用 Containerfile 构建容器镜像。
podman-farm(1)	将构建外包给运行 podman 的不同架构的机器
podman-commit(1)	基于已更改的容器创建新镜像。
podman-completion(1)	生成 shell 自动完成脚本
podman-compose(1)	通过外部 compose 提供程序运行 Compose 工作负载。
podman-container(1)	管理容器。
podman-cp(1)	在容器和本地文件系统之间复制文件/文件夹。
podman-create(1)	创建新的容器。
podman-diff(1)	检查容器或镜像文件系统上的更改。
podman-events(1)	监控 Podman 事件
podman-exec(1)	在正在运行的容器中执行命令。
podman-export(1)	将容器的文件系统内容导出为 tar 存档。
podman-generate(1)	根据容器、Pod 或卷生成结构化数据。
podman-healthcheck(1)	管理容器的健康检查
podman-history(1)	显示镜像的历史记录。
podman-image(1)	管理镜像。
podman-images(1)	列出本地存储中的镜像。
podman-import(1)	导入 tar 包并将其保存为文件系统镜像。
podman-info(1)	显示与 Podman 相关的系统信息。
podman-init(1)	初始化一个或多个容器
podman-inspect(1)	显示容器、镜像、卷、网络或 Pod 的配置。
podman-kill(1)	杀死一个或多个容器中的主进程。
podman-load(1)	将镜像从 tar 存档加载到容器存储中。
podman-login(1)	登录到容器注册表。
podman-logout(1)	注销容器注册表。
podman-logs(1)	显示一个或多个容器的日志。
podman-machine(1)	管理 Podman 的虚拟机
podman-manifest(1)	创建和操作清单列表和镜像索引。
podman-mount(1)	挂载正在运行的容器的根文件系统。
podman-network(1)	管理 Podman 网络。
podman-pause(1)	暂停一个或多个容器。
podman-kube(1)	根据结构化输入文件播放容器、Pod 或卷。
podman-pod(1)	用于管理容器组（称为 Pod）的工具。
podman-port(1)	列出容器的端口映射。
podman-ps(1)	打印有关容器的信息。
podman-pull(1)	从注册表中拉取镜像。
podman-push(1)	将镜像、清单列表或镜像索引从本地存储推送到其他位置。
podman-rename(1)	重命名现有容器。
podman-restart(1)	重启一个或多个容器。
podman-rm(1)	删除一个或多个容器。
podman-rmi(1)	删除一个或多个本地存储的镜像。
podman-run(1)	在一个新容器中运行命令。
podman-save(1)	将镜像保存到存档中。
podman-search(1)	在注册表中搜索镜像。
podman-secret(1)	管理 podman 机密。
podman-start(1)	启动一个或多个容器。
podman-stats(1)	显示一个或多个容器的资源使用情况统计信息的实时流。
podman-stop(1)	停止一个或多个正在运行的容器。
podman-system(1)	管理 podman。
podman-tag(1)	向本地镜像添加其他名称。
podman-top(1)	显示容器的正在运行的进程。
podman-unmount(1)	卸载正在运行的容器的根文件系统。
podman-unpause(1)	取消暂停一个或多个容器。
podman-unshare(1)	在修改后的用户命名空间内运行命令。
podman-untag(1)	从本地存储的镜像中删除一个或多个名称。
podman-update(1)	更新给定容器的配置。
podman-version(1)	显示 Podman 版本信息。
podman-volume(1)	用于管理卷的简单工具。
podman-wait(1)	等待一个或多个容器停止并打印它们的退出代码。

配置檔案

containers.conf (/usr/share/containers/containers.conf, /etc/containers/containers.conf, $HOME/.config/containers/containers.conf)

Podman 具有命令行选项的内置默认值。这些默认值可以使用 containers.conf 配置文件覆盖。

发行版随其默认设置一起提供 /usr/share/containers/containers.conf 文件。管理员可以通过创建 /etc/containers/containers.conf 文件来覆盖此文件中的字段。用户可以通过创建 $HOME/.config/containers/containers.conf 文件进一步修改默认值。Podman 将其内置默认值与来自这些文件（如果存在）的指定字段合并。用户文件中指定的字段会覆盖管理员文件，管理员文件会覆盖发行版文件，发行版文件会覆盖内置默认值。

如果找不到 containers.conf 文件，Podman 将使用内置默认值。

如果设置了 CONTAINERS_CONF 环境变量，则其值将用于 containers.conf 文件，而不是默认值。

mounts.conf (/usr/share/containers/mounts.conf)

mounts.conf 文件指定在执行 podman run 或 podman start 命令时自动挂载到容器内的卷挂载目录。管理员可以通过创建 /etc/containers/mounts.conf 来覆盖默认文件。

当 Podman 在无根模式下运行时，如果存在文件 $HOME/.config/containers/mounts.conf，它会覆盖默认值。有关详细信息，请参阅 containers-mounts.conf(5)。

policy.json (/etc/containers/policy.json, $HOME/.config/containers/policy.json)

签名验证策略文件用于指定策略，例如受信任的密钥，在决定是否接受镜像或该镜像的单个签名作为有效签名时适用。有关详细信息，请参阅 containers-policy.json(5)。

registries.conf (/etc/containers/registries.conf, $HOME/.config/containers/registries.conf)

registries.conf 是配置文件，它指定在完成不包含注册表或域部分的镜像名称时要咨询哪些容器注册表。

Podman 的非 root 用户可以创建 $HOME/.config/containers/registries.conf 文件以代替系统默认值。

如果设置了 CONTAINERS_REGISTRIES_CONF 环境变量，则其值将用于 registries.conf 文件，而不是默认值。

storage.conf (/etc/containers/storage.conf, $HOME/.config/containers/storage.conf)

storage.conf 是使用 containers/storage 的所有工具的存储配置文件

存储配置文件指定使用共享容器存储的工具的所有可用容器存储选项。

当 Podman 在无根模式下运行时，文件 $HOME/.config/containers/storage.conf 将用于代替系统默认值。

如果设置了 CONTAINERS_STORAGE_CONF 环境变量，则其值将用于 storage.conf 文件，而不是默认值。

无根模式

Podman 也可以用作非 root 用户。当 podman 在无根模式下运行时，将为用户自动创建一个用户命名空间，该用户在 /etc/subuid 和 /etc/subgid 中定义。

非 root 用户创建的容器对其他用户不可见，并且不会被以 root 身份运行的 Podman 看到或管理。

需要为用户设置多个 UID/GID。确保用户存在于文件 /etc/subuid 和 /etc/subgid 中。

执行以下命令将范围添加到文件

$ sudo usermod --add-subuids 10000-75535 USERNAME
$ sudo usermod --add-subgids 10000-75535 USERNAME

或者只是手动添加内容。

$ echo USERNAME:10000:65536 >> /etc/subuid
$ echo USERNAME:10000:65536 >> /etc/subgid

有关更多信息，请参阅 subuid(5) 和 subgid(5) 手册页。

注意：/etc/subuid 或 /etc/subgid 中任何行的空格（包括尾随空格）可能会导致没有条目失败。

当指定时，镜像将在 XDG_DATA_HOME 下拉取，否则将在用户的主目录下的 .local/share/containers/storage 下拉取。

目前，需要安装 slirp4netns 或 pasta 来创建网络设备，否则无根容器需要在主机的网络命名空间中运行。

在某些环境（例如 HPC（高性能计算））中，用户无法利用来自 /etc/subuid 和 /etc/subgid 系统的额外 UID 和 GID。但是，在这个环境中，无根 Podman 可以使用单个 UID 运行。要使此方法起作用，请在 containers-storage.conf(5) 文件中设置 ignore_chown_errors 选项。此选项告诉 Podman 在拉取镜像时，在尝试更改容器镜像中的文件以匹配镜像中的非 root UID 时忽略 chown 错误。这意味着所有文件都将以用户的 UID 保存。请注意，这可能会在运行容器时造成问题。

注意：无根模式下不支持的文件系统

在无根模式下，内核版本低于 5.12.9 的系统不支持 Overlay 文件系统 (OverlayFS)。fuse-overlayfs 包是提供用户命名空间中 OverlayFS 功能的工具，允许在无根环境中挂载文件系统。建议安装 fuse-overlayfs 包。在无根模式下，只要未创建 $HOME/.config/containers/storage.conf 文件，Podman 就会自动使用 fuse-overlayfs 程序作为 mount_program（如果已安装）。如果 homedir 中存在 storage.conf，请在 [storage.options.overlay] 下添加 mount_program = "/usr/bin/fuse-overlayfs" 以启用此功能。

在无根模式下，不支持网络文件系统 (NFS) 和其他分布式文件系统（例如：Lustre、Spectrum Scale、通用并行文件系统 (GPFS)），因为这些文件系统不理解用户命名空间。但是，无根 Podman 可以通过修改 $HOME/.config/containers/storage.conf 来使用 NFS Homedir，使 graphroot 选项指向存储在本地（非 NFS）存储上的目录。

另请参阅

containers-mounts.conf(5), containers.conf(5), containers-registries.conf(5), containers-storage.conf(5), buildah(1), oci-hooks(5), containers-policy.json(5), crun(1), runc(8), subuid(5), subgid(5), slirp4netns(1), pasta(1), conmon(8)

疑难解答

有关常见问题的解决方案，请参见 podman-troubleshooting(7)。

有关无根问题的解决方案，请参见 podman-rootless(7)。

历史

2016 年 12 月，最初由 Dan Walsh 编译 dwalsh@redhat.com