A Podman Desktop extension to manage Apple containers on macOS (ARM64 only).
- View and manage Apple containers directly in Podman Desktop
- Designed specifically for macOS on ARM64
- Easy installation and updates via Podman Desktop
- Uses Socktainer under the hood to provide a Docker REST API on top of Apple containers
This extension relies on Socktainer, a lightweight CLI/daemon that exposes a REST API to manage Apple containers. The API is designed to be compatible with the Docker REST API, enabling tools and extensions that expect Docker behavior to work with Apple containers without modification. Podman Desktop interacts with this API to provide a full-featured, user-friendly interface for container management on macOS ARM64.
Install the Apple container extension directly from Podman Desktop:
- Open Podman Desktop →
Extensions→Install custom... - Enter the extension image:
ghcr.io/podman-desktop/extension-apple-container:next
- Click Install ✅
To install a specific release, check available versions and replace
:nextwith:<version>
- Make sure the Apple container system is installed and running:
container system start
container system status
The extension embeds one socktainer binary for each supported Apple container minor version, and starts the one that matches the installed container CLI.
socktainer-versions.json lists the supported versions: it maps each Apple container minor version to its socktainer release. A nightly workflow opens a pull request to update it when new releases come out, so that it covers the last 3 Apple container minor versions.
To check which version is installed:
container system --version
While the Apple connection is running, socktainer serves a Docker-compatible API on ~/.socktainer/container.sock and registers a socktainer Docker context. You can use it with the docker CLI and other Docker clients:
docker context use socktainer
docker ps
Or without changing the current context:
DOCKER_HOST=unix://$HOME/.socktainer/container.sock docker ps
Socktainer doesn't implement the whole Docker API: see the socktainer README for what is supported.
The extension checks the Apple container system every 30 seconds, so a change (installing the CLI, starting the system service, ...) can take up to 30 seconds to show up in Podman Desktop.
The extension runs container system --version. It looks for container in the PATH of Podman Desktop and in the usual install folders: /usr/local/bin (official installer), /opt/homebrew/bin (Homebrew) and /opt/local/bin (MacPorts). Podman Desktop doesn't get your shell PATH when you open it from the Finder or the Dock. If the CLI is installed somewhere else, add a symbolic link to it in one of these folders.
The installed Apple container CLI isn't one of the supported versions, and the Apple provider is in error. Install a supported version: the error goes away on the next check.
The extension starts socktainer only while container system status reports that the system service is running. Start it and check its status:
container system start
container system status
Check that socktainer answers on its socket:
curl --unix-socket ~/.socktainer/container.sock http://localhost/_ping
It prints OK when socktainer and the Apple container system work. If socktainer stopped, the extension starts it again on the next check.
The output of the extension and of socktainer is in the Podman Desktop logs: open the Troubleshooting page and select Logs. Extension lines are tagged with [apple-container], and socktainer output is prefixed with socktainer: or socktainer error:. Please include these lines when you open an issue.
Requirements:
- Node.js, with the version from
.nvmrc - pnpm, with the version from the
packageManagerfield ofpackage.json(corepack enableinstalls it) - macOS on Apple silicon with a supported Apple container version, to run the extension. You can build and test it on any OS.
Build the extension and load it in Podman Desktop running from source (pnpm watch rebuilds the extension when its sources change):
git clone https://github.com/podman-desktop/podman-desktop
git clone https://github.com/podman-desktop/extension-apple-container
cd extension-apple-container
pnpm install
pnpm download-dependencies
pnpm watch
# in another terminal
cd podman-desktop
pnpm install
pnpm watch --extension-folder ../extension-apple-containerpnpm download-dependencies downloads the socktainer binaries of all supported versions to dist/bin/<version>/socktainer. Run it again when socktainer-versions.json changes. Without these binaries, the extension can't start socktainer, and the logs show spawn .../socktainer ENOENT errors.
Before opening a pull request, run the same checks as the CI:
pnpm test # unit tests with coverage
pnpm lint:check # ESLint and Biome lint (pnpm lint:fix to fix)
pnpm format:check # Biome formatting (pnpm format:fix to fix)
pnpm typecheck
pnpm buildCommit messages follow Conventional Commits and are signed off (git commit -s).
We ❤️ feedback! Please open an issue if you encounter bugs or have suggestions.

