🎯 Why kontainy exists

Run Docker and Podman on the same machine for a week and you will meet all of this: docker context use reports success and changes nothing, containers "disappear" after installing Docker Desktop, a memory limit is accepted and silently ignored, a log file quietly fills the root disk, and podman pull nginx fails on a name that works everywhere else.

None of these produce an error message. That is the problem kontainy is built around.

kontainy does not trust the context system. It connects to every socket it finds, separately, and shows them all in one table with an Engine column. A container is never lost — you can see which engine holds it.

The docker CLI resolves its target through five layers, and the top one wins:

1. -H / --host flag
2. DOCKER_HOST environment variable
3. DOCKER_CONTEXT environment variable
4. ~/.docker/config.json → currentContext
5. unix:///var/run/docker.sock

If DOCKER_HOST is set, the context is ignored completely — which is why docker context use can say "success" and do nothing at all. kontainy shows this chain layer by layer and marks the winner.

🧭 Technologies

Every container and virtualisation technology has the same shape under a different name: a set of targets, one of them active, each holding objects. kontainy gives each one the same page — a dropdown of targets at the top, the active one selected, and tabs underneath — and the same ky commands.

A technology that cannot exist on your system is not shown at all.

On every page you can switch the active target, add, remove and test one; start, stop, restart and remove objects one at a time or all at once; manage the system services a technology depends on; install it with the command for your own distribution; and pin new terminals to a target through your shell profile. The line under the dropdown says what the active target really is — rootful · system socket (root), rootless · your user socket, Docker Desktop · Linux engine in WSL 2, remote over SSH.

🪟 On Windows, WSL is the vehicle

WSL is not something kontainy asks you to manage for its own sake. It is what Docker Desktop and podman machine run their Linux engines in — and what kontainy uses to bring the Linux tools to Windows:

• KVM/libvirt, Incus and LXD run inside a WSL 2 distribution. Their pages say via WSL · Ubuntu-24.04 and show every command exactly as it runs: wsl -d Ubuntu-24.04 -- virsh list --all. Installing them uses that distribution's own package manager, as root inside WSL — no Windows administrator rights needed.
• KVM inside WSL needs Windows 11 with nested virtualization. Without it there is no /dev/kvm and QEMU falls back to slow emulation; the KVM page tells you, and how to turn it on (nestedVirtualization=true in .wslconfig).
• Docker and Podman pages carry a Backend tab showing the distribution their engine lives in (docker-desktop, podman-machine-default), with restart, wsl --shutdown and .wslconfig — the usual cures when Docker Desktop stops answering.
• Which distribution carries the Linux tools is kontainy's own setting (ky wsl use NAME). Your default distribution is never changed, and docker-desktop is never used for it.

🎓 Educational by Design

kontainy never hides the command it is running. Create a container, change a setting, apply a fix — the exact shell command appears in the command strip at the bottom of every page, ready to copy. Every command is also written to a persistent history you can export as a shell script.

The point is not convenience. The point is that you should be able to do the same thing without kontainy afterwards.

This runs through the whole application:

• Create Container — the preview grows as you tick boxes, syntax highlighted, and the same definition renders as a docker run command, a systemd Quadlet unit, or a compose service
• Config Catalog — every key shows its CLI equivalent, which file it lives in, and whether a restart is needed
• Diagnostics — every finding ends in a command, and says whether it runs in user scope or needs root
• Learn — every snippet is a command you can actually type, with a Copy button
• History & Log — every command this session, filterable, exportable

📦 Install

pip install kontainy
kontainy          # or the short name:  ky

The same program answers to three names: ky to type, kontainy to read, and kty kept from the first release. On Windows, kontainy-gui opens the window without a console.

# Isolated — recommended, no system packages touched
pipx install kontainy

# Into the system Python — needs the override flag
sudo pip install kontainy --break-system-packages --no-cache-dir -U

Upgrading

pip install -U kontainy --no-cache-dir

Help → Check for Updates asks PyPI — the same place pip looks — and shows the command above, with the --break-system-packages flag added when a system-wide install needs it. It runs in the background, so the window stays usable while the network is slow, and says so plainly when there is no network rather than hanging.

Or download the standalone binary — no Python required:

Linux is the first-class target. Rootless Podman, Quadlet, systemd units, subuid mapping and linger only exist there, and roughly half the diagnostic rules are Linux-specific. The Windows and macOS builds work against Docker Desktop and podman machine, and disable what does not apply.

✨ Features

⚙️ The settings catalogue

This is what kontainy is for. Docker Desktop and Podman Desktop were designed for ease of use, and hide most of the configuration surface as a result — daemon.json gets a raw JSON box with no explanation, containers.conf gets nothing at all.

152 settings — 56 Docker, 67 Podman, 29 shared — spread across ten surfaces:

Every entry carries: the key, the file it lives in, its type and valid choices, the default, the CLI equivalent, whether a restart is needed, user or root scope, a risk level, a description — and for 66 of them, what goes wrong: what breaks when the setting is misunderstood.

Listing a setting is easy. Writing down what happens when it is wrong is not, and no rival tool does it.

🔬 Diagnostics

The equivalent of a linter for your container setup. Every rule says three things: what was found, why it happens, and the command that fixes it.

19 rules, none of which need root to detect:

📦 Templates

You should not have to hunt for example code. Seventeen ready-made definitions, each carrying the details people get wrong when copying from a blog post: the named volume that keeps the data, the environment variable the image will not start without, a health start period long enough for the service to come up, and a capability set that is not simply --privileged.

Each renders three ways from the same definition:

podman run -d \
  --name postgres \
  --restart=unless-stopped \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=<CHANGE_ME> \
  --cap-drop=ALL \
  --cap-add=CHOWN --cap-add=DAC_OVERRIDE --cap-add=FOWNER \
  --cap-add=SETGID --cap-add=SETUID \
  --memory=1g \
  --health-cmd='pg_isready -U postgres' \
  --health-start-period=30s \
  docker.io/library/postgres:16

[Unit]
Description=PostgreSQL 16

[Container]
Image=docker.io/library/postgres:16
PublishPort=5432:5432
Volume=pgdata:/var/lib/postgresql/data
Environment=POSTGRES_PASSWORD=CHANGE_ME
DropCapability=ALL
AddCapability=CHOWN
AutoUpdate=registry

[Service]
Restart=always

[Install]
WantedBy=default.target

services:
  postgres:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    cap_drop:
      - ALL

volumes:
  pgdata:

Quadlet generation is the part no other GUI has. podman generate systemd is deprecated; Quadlet replaced it, and nothing but a text editor writes those units today.

🧱 Create Container

Rival tools give you image, name, ports and volumes. kontainy gives you the whole surface, across seven tabs, with a live command preview underneath:

📚 Learn

kontainy teaches container management, not kontainy. 16 categories, target 204 topics, each with explanation, diagram, table and runnable snippet.

Diagnostic rules link into Learn: the rule tells you what to do, the topic explains why.

🔐 Privilege model

kontainy never elevates privileges. No pkexec, no sudo, no runas.

Writes take a .bak backup, land atomically through os.replace — a half-written daemon.json stops the daemon from starting at all — and preserve existing comments in TOML files, including the ones explaining the very setting being changed.

Rootless Podman keeps its entire configuration under ~/.config, which is why this model costs so little: 65 of the 152 settings are directly editable.

🚀 Quick Start

From PyPI

pip install kontainy
ky

From source

git clone https://github.com/bayramkotan/kontainy.git
cd kontainy
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .

The last line installs the repository in editable mode, which puts the kontainy, ky and kty commands into the virtual environment and points them at the checked-out code — edit a file and ky runs the new version. Activate the environment (source .venv/bin/activate, or .venv\Scripts\activate on Windows) and run:

ky

Running python main.py also works, but installs no commands.

Linux — system dependencies

PySide6 needs the XCB platform libraries. On a minimal install:

# Arch / CachyOS
sudo pacman -S --needed libxcb xcb-util-cursor xcb-util-keysyms \
  xcb-util-wm xcb-util-image xcb-util-renderutil libxkbcommon-x11

# Debian / Ubuntu
sudo apt install libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 \
  libxkbcommon-x11-0 libxcb-keysyms1 libxcb-image0 libxcb-render-util0

# Fedora
sudo dnf install xcb-util-cursor xcb-util-keysyms xcb-util-wm \
  xcb-util-image xcb-util-renderutil libxkbcommon-x11

For Podman support, enable the API socket:

systemctl --user enable --now podman.socket
loginctl enable-linger $USER    # so containers survive logout

CLI

kontainy is a GUI, and everything the GUI does also works headless — on a server with no display, over SSH, or in a script. The command line drives the same code as the window, never loads Qt, and prints the exact command it will run before running it.

Installing gives you the same tool under three names: ky to type, kontainy to read, and kty kept from the first release. On Windows, kontainy-gui opens the window without a console.

Flags that work with every action, anywhere on the line:

$ ky docker stop web
■  Stop
  $ docker --context default stop web
  Sends SIGTERM to web, then SIGKILL after the stop timeout if it has not exited.

Run this? [y/N] y
web

🏗️ Build from source

Builds are made in CI, on each platform's own runner — there is no cross-compilation. Pushing a v* tag runs the whole pipeline: tests, then Windows, macOS ARM64 and Linux AppImage builds, then a GitHub release with a categorised changelog, then PyPI.

python build.py            # one file, windowed   -> dist/kontainy[.exe]
python build.py --debug    # one file, console
python build.py --onedir   # a directory          -> dist/kontainy/

Run the test suite — 245 tests in under four seconds, because PySide6 is stubbed and the suite covers decisions rather than widgets:

pip install pytest
python -m pytest -q

🌍 Translations

The interface is English. A translation layer covering eleven languages is planned; see the project roadmap.

📝 License

MIT — see LICENSE.