Podman 镜像过滤完全指南podman images --filter全部 12 种过滤器详解与源码级原理【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman导读本文围绕 Podman 镜像列表命令的核心选项--filter短选项-f展开系统讲解podman images/podman image list支持的 12 种过滤器id、before、containers、dangling、digest、intermediate、label、manifest、readonly、reference、after/since、until的取值格式、组合用法与实战场景并深入到当前仓库的 CLI 解析、ABI 引擎与 libimage 过滤器实现源码帮助你从「会敲命令」进阶到「理解过滤机制」。关联文档filter.images.md该文件是--filter选项的官方参考页同时被podman images等镜像列表命令复用。一、选项概述--filter, -f*filter*podman images --filter等价于podman image list --filter用于按条件筛选本地镜像存储中的镜像列表。它的基本形式为podman images --filter keyvalue核心规则提供过滤条件filter values一次可指定多个当存在多个过滤器时必须重复传递--filter选项而不是用逗号拼接。官方文档给出的示例为podman images --filter labeltest --filter until10m每个过滤条件遵循filtervalue或filter!value两种格式其中!表示反向匹配取不满足该条件的镜像过滤器与位置参数IMAGE 名称互斥从 list.go 的源码可以看到若同时给出镜像名和过滤器CLI 会直接报错if len(listOptions.Filter) 0 len(args) 0 { return errors.New(cannot specify an image and a filter(s)) } if len(args) 0 { listOptions.Filter append(listOptions.Filter, referenceargs[0]) }有趣的是当只传入镜像名参数时Podman 内部会把它自动转换为referencename过滤器——也就是说「按镜像名过滤」本质上就是reference过滤器的一种快捷写法。过滤器总览表以下为文档中完整列出的全部受支持过滤器必须完整掌握FilterDescriptionidFilter by image ID.beforeFilter by images created before the given IMAGE (name or tag).containersFilter by images with a running container.danglingFilter by dangling (unused) images.digestFilter by digest.intermediateFilter by images that are dangling and have no childrenlabelFilter by images with (or without, in the case of label![...] is used) the specified labels.manifestFilter by images that are manifest lists.readonlyFilter by read-only or read/write images.referenceFilter by image name.after/sinceFilter by images created after the given IMAGE (name or tag).untilFilter by images created until the given duration or time.Shell 自动补全Podman 为--filter提供了原生的 Shell 补全支持。在 completion.go 中可以看到AutocompleteImageFilters函数注册了全部过滤器关键字及其值类型after、before、id、since会补全镜像名/IDcontainers、dangling、intermediate、readonly补全布尔值而label、reference、until、digest则交由用户自行输入。命令行里按两次 Tab 即可体验。二、各过滤器的取值格式与使用详解1.id按镜像 ID 过滤id过滤器接受镜像 ID 字符串即 sha256 摘要的前缀或完整值podman images --filter ida1b2c3 podman images --filter idsha256:1e7a3e...底层实现中filterID对镜像的 ID 做匹配支持前缀模糊匹配因此只需输入 ID 的开头几位即可命中目标镜像。2.before按「早于某镜像创建」过滤before过滤器接受以下三种格式取其一image-name[:tag]镜像名加可选标签如quay.io/podman/hello:latestimage id镜像 IDimagedigest镜像名加 digest如quay.io/podman/hellosha256:...podman images --filter beforequay.io/podman/hello podman images --filter before1e7a3e5f语义只显示创建时间早于指定镜像的镜像。从 filters.go 的源码可以看到before会先解析出目标镜像再取其Created()时间套用filterBefore(img.Created())做时间比较。3.containers按「是否有运行中容器」过滤containers过滤器显示有基于该镜像的运行中容器的镜像podman images --filter containerstrue podman images --filter containersfalse # 反向没有运行容器的镜像注意containers过滤的是「running container」运行中的容器。实现上它还会借助IsExternalContainerFunc把外部存储中的容器一并纳入判断见 filters.go也就是说由其他工具如 buildah创建的容器只要其根文件系统与本地镜像相关也会被计入。4.dangling按「悬空镜像」过滤dangling过滤器用于筛选悬空dangling镜像。官方文档对 dangling 镜像的定义是悬空镜像是在某次镜像构建中使用的文件系统层如今已不再被任何镜像引用。它们以none标签标注占用磁盘空间且不再提供任何实际用途。podman images --filter danglingtrue podman images --filter danglingfalsedanglingtrue正是清理构建遗留层的标准入口——配合podman image prune即可安全回收这部分磁盘空间。源码中该过滤器会触发needsLayerTree true意味着 Podman 需要构建镜像层树layer tree来判断某个镜像是否还有子节点引用其层见 filters.go。在podman images的输出中悬空镜像的仓库与标签通常显示为none/none。5.digest按 digest 过滤digest过滤器接受镜像 digest 字符串podman images --filter digestsha256:8d3ac348f6f...它直接对镜像的 digest 进行匹配。若想同时看到输出中的 digest 列可叠加--digests选项podman images --digests --filter digestsha256:8d3ac348f6f...6.intermediate按「中间镜像」过滤intermediate过滤器显示悬空且没有子镜像的镜像即构建过程中产生的中间层镜像podman images --filter intermediatetrue podman images --filter intermediatefalse这是一个需要特别说明的过滤器。从 images_list.go 的 ABI 引擎实现可以看出 Podman 的默认行为if !opts.All !slices.Contains(listImagesOptions.Filters, intermediatetrue) { // Filter intermediate images unless we want to list *all*. // NOTE: its a positive filter, so intermediatefalse means // to display non-intermediate images. listImagesOptions.Filters append(listImagesOptions.Filters, intermediatefalse) }即默认情况下podman images会隐藏中间镜像等价于自动追加intermediatefalse。只有显式指定--all-a或--filter intermediatetrue时才会显示它们。这与dangling一样需要构建层树来判断父子关系。7.label按标签过滤label过滤器支持两种格式这也是全部过滤器中唯一通过!提供「无标签」反向语义的典型代表labelkey显示具有该标签键的镜像labelkeyvalue显示具有该标签键且值匹配的镜像label!key或label!keyvalue显示不具有该标签或标签值不匹配的镜像。podman images --filter labelmaintainer podman images --filter labelversion1.2.0 podman images --filter label!deleted # 没有 deleted 标签的镜像 podman images --filter labeltest --filter until10m官方文档特别提示当需要「显示不包含某标签的镜像」时使用label![...]写法即可。这也是文首示例中--filter labeltest --filter until10m组合用法的来源。8.manifest按 manifest 列表过滤manifest过滤器用于筛选manifest 列表manifest lists即多架构镜像索引podman images --filter manifesttrue podman images --filter manifestfalse在podman manifest create或podman build --platform生成多架构镜像后可用此过滤器快速定位这些 manifest 列表。实现上它调用filterManifest对每个镜像执行「是否为 manifest list」的判断。9.readonly按只读属性过滤readonly过滤器接受true或falsepodman images --filter readonlytrue # 只读镜像如基于只读存储驱动的镜像 podman images --filter readonlyfalse # 可读写镜像从 images_list.go 看镜像摘要中的ReadOnly字段来自img.IsReadOnly()对应地podman images输出中会视情况显示R/O列表头映射见 list.go。10.reference按镜像名称过滤支持正则reference过滤器接受正则表达式例如官方文档给出的image:.*-alpinepodman images --filter referencequay.io/podman/.* podman images --filter reference.*:latest podman images --filter referenceimage:.*-alpine podman images --filter reference!.*:latest # 反向匹配reference是行为最特殊的一个过滤器源码中有专门注释说明其匹配逻辑见 filters.goreference filters is a special case as it does an OR for positive matches and an AND logic for negative matches即多个正向reference匹配之间是「或」关系只要匹配其中一个正则即命中而反向reference!匹配之间是「与」关系且正向与反向可同时叠加。举例# 命中 A 或 B 任一正则 podman images --filter reference.*/foo/.* --filter reference.*/bar/.*另请注意任何单独的镜像名位置参数都会被改写成reference过滤器见第一节所以podman images quay.io/podman/hello与podman images --filter referencequay.io/podman/hello在语义上等价。11.after/since按「晚于某镜像创建」过滤after与since是完全等价的别名接受的格式与before相同image-name[:tag]image idimagedigestpodman images --filter afterquay.io/podman/hello podman images --filter since1e7a3e5f语义显示创建时间晚于指定镜像的镜像。源码中after/since会统一归一化为since键并套用filterAfter(img.Created())见 filters.go。12.until按创建时间上限过滤until过滤器显示创建时间早于给定时间点的镜像。timestamp支持三种写法Unix 时间戳如1700000000日期格式化时间戳如2020-12-31、2021-01-01T10:00:00Go 时长字符串如10m、1h30mpodman images --filter until2020-12-31 podman images --filter until2021-01-01T10:00:00 podman images --filter until10m # 10 分钟前创建的 podman images --filter until1h30m # 1 小时 30 分钟前创建的实现上r.until(value)负责解析时间支持上述三种格式最终与before一样套用filterBefore(until)见 filters.go。until常与label组合用于「找出旧版本构建产物并批量清理」。三、过滤器的组合与实战场景3.1 多条件组合条件之间默认是 AND 关系多次传递--filter时各过滤器之间按**逻辑与AND**叠加唯一的例外是多个正向reference之间为 OR见上文。例如# 有运行中容器、且带 version1.2.0 标签的镜像 podman images --filter containerstrue --filter labelversion1.2.0 # 10 分钟前创建的悬空镜像清理目标清单 podman images --filter danglingtrue --filter until10m3.2 实战清理磁盘空间的完整流程dangling 与 intermediate 是镜像清理场景的核心# 第一步找出悬空镜像占用磁盘、无实际用途以 none 标签呈现 podman images --filter danglingtrue # 第二步回收悬空镜像占用的层 podman image prune # 第三步查看所有中间镜像默认列表会隐藏它们 podman images -a --filter intermediatetrue # 第四步清理全部未使用的镜像含悬空与无引用镜像 podman image prune -a3.3 实战按构建时间窗口管理镜像# 今天之前拉取/构建的所有镜像 podman images --filter until2026-09-18 # 指定镜像之后出现的所有镜像排查依赖升级影响面 podman images --filter sincequay.io/podman/hello:latest # 用正则圈定某一命名空间下的所有镜像 podman images --filter referencequay.io/myteam/.*3.4 与其他选项的搭配--filter可自由与podman images的其他输出选项组合例如# 仅输出命中条件的镜像 ID便于脚本化处理 podman images --quiet --filter danglingtrue # 以 JSON 输出筛选结果 podman images --format json --filter labelversion1.2.0 # 追加 digest 列 podman images --digests --filter digestsha256:... # 指定排序后输出 podman images --sort size --filter containerstrue其中--quiet/-q、--format、--digests、--sort支持 created/id/repository/size/tag见 list.go均为同命令的兄弟选项可直接组合使用。四、源码级原理过滤器是如何被解析与执行的4.1 命令行入口字符串数组的收集--filter被定义为可重复的字符串数组StringArrayVarP每出现一次--filter keyvalue就追加一个元素见 list.goflags.StringArrayVarP(listOptions.Filter, filterFlagName, f, []string{}, Filter output based on conditions provided (default [])) _ cmd.RegisterFlagCompletionFunc(filterFlagName, common.AutocompleteImageFilters)4.2 解析规则与!在 libimage 的过滤器编译阶段filters.go每个过滤字符串按下述规则拆分key, value, ok : strings.Cut(f, !) // 先尝试 ! 分隔 if ok { negate true } else { key, value, ok strings.Cut(f, ) // 再尝试 分隔 if !ok { return 格式错误 } }也就是说key!value→ 反向过滤器negate true最终结果取反negateFilterkeyvalue→ 正向过滤器既无也无!→ 直接报错invalid image filter。若使用了文档与代码中均未列出的未知键也会得到同样的格式错误default分支。4.3 特殊处理的过滤器从编译源码中可以归纳出三类特殊处理详见 filters.go时间类过滤器after/since/before/until先解析出时间点再统一转为「创建时间早于/晚于」的比较器布尔类过滤器dangling/intermediate/readonly/manifest/containers解析为true/false且同一键多次出现但值不同会报错duplicatemap 检查其中dangling与intermediate会触发needsLayerTree需要构建镜像层树进行父子关系判定reference过滤器不参与常规的逐条 AND 组装而是单独收集正/反两个正则列表最后统一按「正向 OR 反向 AND」的组合执行。4.4 数据流向从 CLI 到存储层完整调用链为podman images命令list.go收集--filter数组本地/ABI 模式下进入ImageEngine.Listimages_list.go将过滤器透传给libimage.ListImagesOptions.Filters并按默认策略追加intermediatefalse隐藏中间镜像libimage 运行时对每个过滤器逐一编译成filterFunc(img, layerTree) (bool, error)并组合执行命中后收集进[]*ImageSummary回到 CLI 层经sortImages排序后按--format/--quiet/默认表格输出list.go。远程tunnel模式下同样走ImageEngine.List见 pkg/domain/infra/tunnel/images.go过滤器字符串会被序列化后交由服务端执行——因此这些过滤器在podman-remote images下同样可用。五、常见误区与注意事项多个过滤器不要用逗号拼接--filter a1,b2会被当作单个非法过滤条件而报错正确写法是--filter a1 --filter b2。不要同时传镜像名与过滤器podman images nginx --filter danglingtrue会直接报cannot specify an image and a filter(s)只想按名称过滤请用--filter referencenginx。默认隐藏中间镜像podman images默认输出不含中间镜像等效intermediatefalse这是刻意为之的默认值要查看全部需加--all或显式--filter intermediatetrue。label!是反向语义的典型用法--filter label!key表示「不含该标签」注意!与的书写位置差异。until与before容易混淆until接收时间戳/日期/时长before接收镜像名/ID/digest——一个是时间点一个是参照镜像。大小写敏感过滤器键名必须小写如dangling、intermediate、readonlyReference之类的大小写变体会落入未知键分支被拒绝。六、延伸阅读选项官方参考文档docs/source/markdown/options/filter.images.mdpodman images命令实现参数解析、排序、输出cmd/podman/images/list.goABI 引擎层过滤透传与intermediatefalse默认策略pkg/domain/infra/abi/images_list.golibimage 过滤器编译与执行全部 12 种 filter 的 case 分支vendor/go.podman.io/common/libimage/filters.go--filter的 Shell 补全定义cmd/podman/common/completion.go远程模式下的对应实现pkg/domain/infra/tunnel/images.go掌握上述 12 种过滤器及其组合规则即可在镜像管理、磁盘清理、构建产物审计等日常运维场景中精准定位目标镜像实现高效可控的镜像生命周期管理。【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考