Troubleshooting

"boks: command not found"

The boks binary is not on your PATH.

  1. Verify the binary exists: ls ~/.local/bin/boks
  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"

boks finds neither Podman nor Docker on your PATH (boks 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:

boks --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:

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

Tool not found in index

image resolution failed for "mytool"
  1. Search the index: boks --search mytool
  2. Refresh the index to make sure it's current: boks --update
  3. If still not found, add a mapping to boks.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 boks keeps using the old environment:

  1. The cache key is a hash of the file contents — verify the file actually changed
  2. Run boks --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 boks python@...
  2. The script must be executable: chmod +x script.py
  3. boks must be on your PATH: which boks

Getting help