Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pratyay360/podman-ts/llms.txt

Use this file to discover all available pages before exploring further.

ImagesManager provides a high-level interface for working with OCI and Docker container images. It is accessible via client.images on any PodmanClient instance and covers the full image lifecycle including pulling from registries, building from a Dockerfile context, pushing, tagging, and removal.

​
ImagesManager methods

​
list

list(options?: ImageListOptions): Promise<Image[]>
List images stored locally.
​
options.name
string
Filter by image reference. Internally mapped to the reference filter parameter.
​
options.all
boolean
Include intermediate build layers.
​
options.filters
Record<string, string | string[]>
Additional key/value filters (e.g. { dangling: "true" }).

​
get

get(name: string): Promise<Image>
Inspect a local image by name or ID. Returns an Image instance. Throws ImageNotFound if the image does not exist.

​
pull

pull(repository: string, options?: ImagePullOptions): Promise<Image>
Pull an image from a registry. Returns the pulled Image instance.
​
options.tag
string
Tag to pull (e.g. "latest"). When set, the full reference becomes repository:tag.
​
options.allTags
boolean
Pull all tags for the repository.
​
options.quiet
boolean
Suppress progress output.
​
options.tlsVerify
boolean
Verify TLS certificates for the registry. Set to false for insecure registries.

​
push

push(repository: string, options?: ImagePushOptions): Promise<void>
Push an image to a registry. The image must already be tagged with the destination reference.
​
options.tag
string
Specific tag to push.
​
options.tlsVerify
boolean
Verify TLS certificates for the destination registry.

​
build

build(options: BuildOptions): Promise<{ image: Image; logs: string[] }>
Build an image from a Dockerfile context directory. The context is packaged into a tar archive using Bun.spawn(["tar", ...]) and POSTed to /build.
build() uses Bun.spawn to create the tar archive. This method requires the Bun runtime and will not work under Node.js.
Returns { image, logs } where image is the resulting Image instance and logs is the raw build output split by line. See BuildOptions below for the full list of parameters. 
search(term: string, options?: ImageSearchOptions): Promise<Record<string, unknown>[]>
Search configured registries for images matching the given term.
​
options.limit
number
Maximum number of results to return.
​
options.filters
Record<string, string>
Search filters (e.g. { "is-official": "true" }).
​
options.tlsVerify
boolean
Verify TLS for registry connections.
​
options.listTags
boolean
Include available tags in results.

​
exists

exists(name: string): Promise<boolean>
Return true if an image with the given name or ID is present locally, false otherwise.

​
remove

remove(name: string, options?: { force?: boolean }): Promise<Record<string, unknown>[]>
Remove an image by name or ID. Returns a list of untagged/deleted layer records. Throws ImageNotFound if the image does not exist.
​
options.force
boolean
Force removal even if the image is in use by a container.

​
prune

prune(options?: { all?: boolean; filters?: Record<string, string> }): Promise<Record<string, unknown>>
Remove unused images and reclaim disk space.
​
options.all
boolean
Remove all unused images, not just dangling ones.
​
options.filters
Record<string, string>
Prune filters (e.g. { until: "24h" }).

​
Image instance methods

An Image object is returned by get(), pull(), and build(), and each element of list().
MethodSignatureDescription
history(): Promise<Record<string, unknown>[]>Return the layer history of the image.
tag(repository: string, tag?: string): Promise<boolean>Add a tag to the image.
remove(options?: { force?: boolean }): Promise<Record<string, unknown>[]>Remove the image.
reload(): Promise<void>Refresh image.attrs from the API (equivalent to re-inspecting).
Accessor properties: image.id, image.tags (filtered RepoTags), image.labels.
There is no standalone inspect() method on an Image instance. Use client.images.get(name) for fresh inspect data, or call image.reload() to update the instance’s cached attributes in place.

​
BuildOptions

Full reference for options accepted by client.images.build():
​
path
string
required
Absolute path to the build context directory. The entire directory is packaged as a tar and sent to the daemon.
​
dockerfile
string
default:"\"Dockerfile\""
Dockerfile/Containerfile name relative to path.
​
tag
string
Name and optionally a tag for the resulting image (e.g. "myapp:v1").
​
buildargs
Record<string, string>
Build-time variables passed as --build-arg (e.g. { VERSION: "1.2.3" }).
​
target
string
Target build stage in a multi-stage Dockerfile.
​
nocache
boolean
Disable the layer cache.
​
pull
boolean
Always attempt to pull a newer version of base images.
​
rm
boolean
Remove intermediate containers after a successful build.
​
forcerm
boolean
Always remove intermediate containers, even on failure.
​
quiet
boolean
Suppress build output.
​
platform
string
Target platform (e.g. "linux/arm64").
​
networkMode
string
Network mode for the build container (e.g. "host", "none").
​
squash
boolean
Squash all layers into a single layer.
​
cacheFrom
string[]
Images to use as cache sources.
​
extraHosts
Record<string, string>
Additional host-to-IP mappings for the build container.
​
labels
Record<string, string>
Labels applied to the resulting image.
​
secrets
string[]
Secret IDs to expose during the build.
​
shmsize
number
Size of /dev/shm in bytes.
​
layers
boolean
default:"true"
Cache intermediate layers.
​
httpProxy
boolean
Pass HTTP_PROXY/HTTPS_PROXY environment variables to the build.
​
manifest
string
Add the built image to the named manifest list.
​
containerLimits
object
Resource limits for the build container.

​
Code examples

​
Pull an image

import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();

const image = await client.images.pull("docker.io/library/nginx", { tag: "latest" });
console.log("Pulled:", image.tags);

​
Build from a Dockerfile context directory

const { image, logs } = await client.images.build({
  path: "/home/user/myapp",
  dockerfile: "Dockerfile",
  tag: "myapp:dev",
  buildargs: { NODE_ENV: "production" },
  nocache: true,
});

console.log("Built image ID:", image.id);
console.log("Build log lines:", logs.length);

​
Push to a registry

// Tag the image with the destination reference first.
const image = await client.images.get("myapp:dev");
await image.tag("registry.example.com/myorg/myapp", "v1.0.0");

// Then push.
await client.images.push("registry.example.com/myorg/myapp", { tag: "v1.0.0" });

​
Search registries

const results = await client.images.search("nginx", {
  limit: 10,
  filters: { "is-official": "true" },
});

for (const result of results) {
  console.log(result["Name"], result["Description"]);
}

​
List local images

const images = await client.images.list({ name: "nginx" });
for (const img of images) {
  console.log(img.id, img.tags.join(", "));
}

Build docs developers (and LLMs) love

Get started for freeTalk to us