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.

Podman Quadlets are declarative unit files that describe how to run a container (or pod, volume, or network) as a systemd service. Instead of writing a raw [Service] unit by hand, you write a Quadlet file (e.g. myapp.container) and Podman’s systemd generator translates it into a fully managed service. QuadletsManager gives you a TypeScript interface to install, inspect, read, and remove those unit files programmatically. Access it via client.quadlets on any PodmanClient instance.

​
QuadletsManager methods

​
list

list(options?: { filters?: Record<string, string> }): Promise<Quadlet[]>
Return all installed Quadlet units. If no quadlets are installed, an empty array is returned rather than an error.
​
options.filters
Record<string, string>
Server-side key/value filters to narrow the result set (e.g. { name: "myapp" }).

​
get

get(name: string): Promise<Quadlet>
Fetch a single Quadlet by name. Throws NotFound if no unit with that name exists.

​
exists

exists(key: string): Promise<boolean>
Return true if a Quadlet with the given name is installed, false otherwise. Does not throw.

​
install

install(
  files: QuadletFileItem | QuadletFileItem[],
  options?: { replace?: boolean; reloadSystemd?: boolean }
): Promise<Record<string, unknown>>
Install one or more Quadlet unit files. QuadletFileItem can be:
  • A [filename, content] tuple — the filename should include the extension (e.g. "myapp.container"); content may be a string or Uint8Array.
  • A file path string to a local .quadlet file, or a path to a .tar / .tar.gz archive containing multiple unit files.
​
files
QuadletFileItem | QuadletFileItem[]
required
Unit file(s) to install. See the description above for the accepted shapes.
​
options.replace
boolean
default:"false"
Overwrite an existing unit file with the same name.
​
options.reloadSystemd
boolean
default:"true"
Run systemctl daemon-reload after installation so systemd picks up the new unit.
When you pass a single .tar or .tar.gz path, the archive is uploaded directly. All other cases use a multipart form upload. Mixed arrays of paths and tuples are supported.

​
getContents

getContents(name: string | Quadlet): Promise<string>
Return the raw text content of an installed unit file. Useful for inspecting or validating a Quadlet before modifying it.

​
delete

delete(
  name?: string | Quadlet | null,
  options?: {
    force?: boolean;
    ignore?: boolean;
    reloadSystemd?: boolean;
    all?: boolean;
  }
): Promise<string[]>
Delete one or more Quadlet unit files. Returns a list of removed unit names.
​
name
string | Quadlet | null
Name or Quadlet instance to delete. Required unless options.all is true.
​
options.force
boolean
default:"false"
Stop the associated service before deleting the unit file.
​
options.ignore
boolean
default:"false"
Do not error if the named unit is not found.
​
options.reloadSystemd
boolean
default:"true"
Run systemctl daemon-reload after deletion.
​
options.all
boolean
Delete all installed Quadlet units. When set, name is ignored.
Calling delete() without a name and without all: true throws a PodmanError. Always provide one or the other.

​
Quadlet instance methods

A Quadlet object is returned by install(), get(), and list(). It exposes:
MethodSignatureDescription
getContents(): Promise<string>Return the raw text of this unit file.
delete(options?: { force?: boolean; ignore?: boolean; reloadSystemd?: boolean }): Promise<string[]>Delete this unit file. Returns the list of removed names.

​
Quadlet instance properties

PropertyTypeDescription
namestringUnit file name (e.g. "myapp.container").
unitNamestringSystemd unit name generated by the Quadlet generator.
pathstringFilesystem path where the unit file is installed.
statusstringCurrent systemd service status.
applicationstringApplication name from the unit’s App field.

​
Code examples

​
Install a Quadlet from inline content

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

const client = new PodmanClient();

const unitContent = `
[Unit]
Description=My web application

[Container]
Image=docker.io/library/nginx:latest
PublishPort=8080:80

[Install]
WantedBy=default.target
`;

const result = await client.quadlets.install(
  ["myapp.container", unitContent],
  { replace: true, reloadSystemd: true },
);

console.log("Installed:", result);

​
Install multiple Quadlet files at once

const result = await client.quadlets.install(
  [
    ["frontend.container", frontendUnitContent],
    ["backend.container", backendUnitContent],
  ],
  { reloadSystemd: true },
);

console.log("Installed units:", result);

​
Install from a local tar archive

// A .tar or .tar.gz path is detected automatically and uploaded as a single archive.
const result = await client.quadlets.install("/path/to/units.tar.gz", {
  replace: true,
});

console.log("Installed from archive:", result);

​
List installed Quadlets

const quadlets = await client.quadlets.list();

for (const q of quadlets) {
  console.log(`${q.name} — ${q.status} (${q.path})`);
}

​
Read the contents of a Quadlet file

const quadlet = await client.quadlets.get("myapp.container");
const contents = await quadlet.getContents();

console.log(contents);

​
Delete a Quadlet unit

const removed = await client.quadlets.delete("myapp.container", {
  force: true,
  reloadSystemd: true,
});

console.log("Removed:", removed);
Pass ignore: true when deleting in a teardown script where the unit may or may not be present. This prevents errors from halting your cleanup flow.

​
Delete all Quadlets

const removed = await client.quadlets.delete(null, { all: true });
console.log("All removed:", removed);

Build docs developers (and LLMs) love

Get started for freeTalk to us