Troubleshooting

"kapsl: command not found"

The kapsl binary is not on your PATH.

  1. Verify the binary exists: ls ~/.local/bin/kapsl
  2. Add ~/.local/bin to your PATH:
    export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc
  3. Reload: source ~/.bashrc

"No container runtime found"

kapsl finds neither Podman nor Docker on your PATH (kapsl falls back to Docker automatically when Podman is absent).

  1. Install Podman (recommended):
    • Linux: sudo apt install podman or sudo dnf install podman
    • macOS: install Podman Desktop from podman.io
  2. Verify: podman --version
  3. On macOS, start the machine: podman machine start

An existing Docker installation also works — no configuration needed.

Podman machine not running (macOS)

Error: unable to connect to Podman socket

Start the Podman machine:

podman machine start

To start it automatically, add the command to your shell profile or use Podman Desktop's auto-start option.

"Read-only file system" when trying to write

By default, the working directory is mounted read-only. Use --cap rw to allow writes:

kapsl --cap rw python -c "open('out.txt', 'w').write('done')"

"Could not resolve host" inside container

Network access is disabled by default. Use --cap net:

kapsl --cap net curl https://example.com

Tool not found in index

image resolution failed for "mytool"
  1. Search the index: kapsl --search mytool
  2. Refresh the index to make sure it's current: kapsl --update
  3. If still not found, add a mapping to kapsl.toml:
    [tools]
mytool = "docker.io/myorg/mytool:latest"

Slow first run

The first run for any tool pulls the container image from the registry. This is normal and only happens once per image. Subsequent runs use the local cache.

Environment not rebuilding

If you changed your requirements.txt but kapsl keeps using the old environment:

  1. The cache key is a hash of the file contents — verify the file actually changed
  2. Run kapsl --clean to remove all cached environments and force a rebuild

Shebang not working

If ./script.py gives a "bad interpreter" error, check:

  1. The first line must be exactly #!/usr/bin/env -S kapsl python@...
  2. The script must be executable: chmod +x script.py
  3. kapsl must be on your PATH: which kapsl

Getting help