Kompose: converting Compose files into Kubernetes manifests

The gap Kompose fills between compose.yaml and a cluster

A docker-compose file describes services, images, ports, volumes, networks and dependencies in a form that is convenient on a single machine. Kubernetes wants Deployments, Services, PersistentVolumeClaims, ConfigMaps and Ingress objects, each with its own schema and its own defaults. Rewriting a multi-service Compose file by hand is mechanical work, and the mechanical parts are exactly where people make mistakes: a port mapping that becomes a Service with the wrong targetPort, a named volume that becomes an emptyDir, an env_file that never gets interpolated.

Kompose targets the developer who already runs the stack locally with Compose and now wants to see it on Kubernetes. The README frames it as "a convenience tool to go from local Compose environment to managing your application with Kubernetes." That framing matters. The output is a scaffold you are expected to review, not a finished chart. If you are an operator who already maintains Helm charts, Kompose is not aimed at you. If you are a developer who has never written a Kubernetes manifest and wants to learn the shape of one by diffing it against a Compose file you understand, the tool is a reasonable first step.

What the converter actually reads and writes

Kompose parses the Compose Specification. The go.mod file pins github.com/compose-spec/compose-go/v2 at v2.10.0, which is the same Go library used elsewhere in the Compose ecosystem, so the input surface is the spec rather than a private dialect of docker-compose. On the output side it depends on k8s.io/api and k8s.io/apimachinery at v0.31.2 and serialises manifests with gopkg.in/yaml.v3. The CLI layer is cobra with pflag and viper, which is why the command surface looks like kubectl or helm in its flag style.

The data flow is a straight pipeline. Compose file in, an internal model of services, volumes and networks, then a set of Kubernetes objects written to disk as YAML. The README's own example shows the output naming convention: a service called frontend produces frontend-service.yaml and frontend-deployment.yaml. There is no apply step, no cluster connection required for the basic conversion, and no state kept between runs. That is the whole architecture, and it is why the tool is small and why it cannot reconcile drift later.

One consequence of reading the Compose Specification rather than docker-compose's older v2 format is that features which only make sense locally (build contexts, bind mounts from the host, the deploy key's non-Swarm subset) have no clean Kubernetes equivalent. The repository keeps a docs/conversion.md page precisely because the mapping needs explaining case by case.

Installing Kompose and converting a first file

The README states that the preferred installation method is downloading the binary from the latest GitHub release, and that the full list of methods lives in docs/installation.md. For Linux and macOS the release page provides per-architecture binaries. The commands below are the ones given in the README for v1.38.0; substitute the current release tag if you are reading this later. After moving the binary onto your PATH, run kompose --help to confirm it executes.

# Linux
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-linux-amd64 -o kompose

# macOS
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-darwin-amd64 -o kompose

chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose

On Windows the README points at kompose-windows-amd64.exe on the release page and says to add the binary to your PATH. There is also a Dockerfile in the repository that builds a small Alpine image by downloading the release binary matching the build/VERSION file, so the container route does not compile from source.

With the binary in place, conversion is one command against a Compose file. The README uses examples/compose.yaml, a Redis frontend/leader/replica example, and shows the INFO lines it prints as each file is written. Run it in an empty directory so the generated YAML is easy to spot.

kompose convert -f compose.yaml

You should see one INFO line per created file, for example frontend-service.yaml and frontend-deployment.yaml. From there kubectl apply -f . is the obvious next step, but read the generated Deployments first: image tags, replica counts and volume claims are the fields most likely to need editing before anything reaches a cluster.

Shell completion is available for Bash, Zsh and Fish. The README gives these forms, and notes that the Bash and Zsh variants should be added to your rc file for persistence.

source <(kompose completion bash)
source <(kompose completion zsh)
kompose completion fish | source

Where the conversion stops being a faithful translation

The README is direct about this: "Transformation of the Compose Specification format to Kubernetes resources manifest may not be exact." That sentence is doing a lot of work. Compose is a single-host model. Networks are a shared bridge, volumes are directories on the same machine, and depends_on is an ordering hint. Kubernetes has none of those primitives in the same form. A Compose network becomes a Service or nothing depending on the case, a bind mount has no portable equivalent, and depends_on has no direct Kubernetes counterpart at all.

The practical failure mode is a manifest set that applies cleanly and then behaves differently. A service that started after its database locally may now start in parallel and crash-loop until the database is ready. A container that wrote to a host directory may now write to a volume that is discarded when the pod is replaced. None of this is a bug in the converter; it is the boundary between the two models, and the tool cannot paper over it because the information needed to do so is not in the Compose file.

The second boundary is lifecycle. Kompose has no watch mode, no reconciliation and no cluster state. Every run is a fresh conversion. If you edit compose.yaml a month later, you re-run the command and diff the output yourself. Teams that want the Compose file to remain the source of truth for a running cluster are looking at the wrong tool, and the README does not claim otherwise.

Kompose compared with Helm and with writing manifests by hand

Helm and Kompose sit at different stages of the same journey, and the difference is in what each one treats as the source of truth. Helm takes a chart, which is a templated set of Kubernetes manifests plus values files, and installs or upgrades a release in a cluster while tracking that release's history. Kompose takes a Compose file and emits plain manifests, then exits. It never talks to a cluster and keeps no record.

That means the two are complementary rather than competing in the ordinary case. A common path is to convert once with Kompose, read the output to understand which Kubernetes objects your services need, then fold those objects into a chart with parameterised values. Doing the conversion first is often faster than starting from an empty chart, because the generated YAML already has the ports, env vars and volume wiring in roughly the right place.

The alternative to both is writing the manifests yourself. That is the right choice when the Compose file is small, when you already know the Kubernetes API, or when the deployment needs objects Kompose does not emit, such as a StatefulSet with stable identity or a custom resource. Hand-written manifests also avoid the review problem that generated YAML creates: nobody on the team owns a file that a tool produced, and unowned manifests drift.

Release cadence, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-18. Releases are cut on a cadence the README describes as a three-week cycle; the recent tags are v1.38.0 on 2026-01-15, v1.37.0 on 2025-08-11 and v1.36.0 on 2025-05-14, so the actual spacing between those three is wider than three weeks. Treat the cadence claim as the project's stated intent rather than a schedule you can plan around.

Upgrade cost is low for the binary itself. It is a single static Go binary, and the Makefile builds with CGO_ENABLED=0, so there are no shared-library surprises between machines. The cost that matters is on the other side: the Kubernetes API versions Kompose emits move with its k8s.io/api dependency, pinned at v0.31.2 in go.mod. If your cluster is older than the API versions in the generated YAML, you will be editing apiVersion fields after every upgrade. Pin the Kompose version in CI and re-run the conversion deliberately rather than tracking latest.

The project is Apache-2.0. That is a permissive licence, and the practical implication for most users is that generated YAML carries no licence obligation from the tool, because the output is your configuration, not a derivative of Kompose's source. The LICENSE file and the Kubernetes community code-of-conduct.md govern contributions. Nothing here is legal advice; if you redistribute a modified Kompose binary, read the Apache-2.0 terms and the NOTICE handling yourself.

Editorial conclusion

Adopt Kompose if you already have a working compose.yaml and want a first set of Kubernetes manifests to read, edit and apply, and if you accept that the output is a starting point rather than a finished deployment. Do not adopt it as a deployment tool that keeps a cluster in sync with a Compose file; it is a one-way converter, and the README states the transformation may not be exact. Before you commit to the output, verify how your volumes, networks, build sections and environment interpolation survive the conversion, and check the docs/conversion.md page for the mapping rules that apply to your file.

Frequently asked questions

Official sources

1. kubernetes/kompose on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases