Skip to main content

Running Kurtosis in Podman

This guide assumes that you have Kurtosis installed.

If you would like more information on Podman and how to set up and manage a Podman environment, check out these official docs.

I. Set Up Podman​

  1. Install Podman on your system following the official installation guide.

  2. Start the Podman socket service:

podman machine init
podman machine start
  1. Configure Docker CLI to use Podman by setting the DOCKER_HOST environment variable:
export DOCKER_HOST="unix://$HOME/.local/share/containers/podman/machine/podman.sock"
Docker Compatibility

Podman provides a Docker-compatible CLI and API. This means you can use Docker commands with Podman by either:

  • Setting the DOCKER_HOST environment variable as shown above
  • Using the podman command directly (it accepts the same commands as docker)
  • Using the podman-docker package which creates a symlink from docker to podman

For more information on Docker compatibility, see the Podman documentation.

II. Add Podman Cluster to kurtosis-config.yml​

  1. Open the file located at "$(kurtosis config path)". This should look like /Users/<YOUR_USER>/Library/Application Support/kurtosis/kurtosis-config.yml on MacOS.

  2. Add a new cluster configuration for Podman. The configuration is identical to Docker since Podman is Docker-compatible:

config-version: 6
should-send-metrics: true
kurtosis-clusters:
  docker:
    type: "docker"
    ...
  podman:
    type: "podman"
    ...

III. Configure Kurtosis​

Run kurtosis cluster set podman. This will start the engine using Podman as the container runtime.

Done! Now you can run any Kurtosis command or package just like if you were doing it locally with Docker.

Switching Back

To switch back to using Kurtosis with Docker, simply use: kurtosis cluster set docker