Installation¶
Prerequisites:
Python >= 3.10 (CPython and PyPy are officially tested and supported).
A Kubernetes cluster (k3d/k3s, minikube, OrbStack, Docker, AWS, GCP, etc).
Running without installation¶
Using uvx¶
To run Kopf as a tool via uvx with an operator:
uvx kopf --help
uvx kopf run --help
uvx kopf run -v examples/01-minimal/example.py
Using docker¶
A pre-built Docker image with all extras is available for quick experimentation — no local Python installation needed:
# Minimize the credentials exposure.
kubectl config view --minify --flatten > dev.kubeconfig
# Run the operator locally, target a local cluster (host networking).
docker run --rm -it --network=host \
-v ./examples/01-minimal/example.py:/app/main.py:ro \
-v ./dev.kubeconfig:/root/.kube/config:ro \
ghcr.io/nolar/kopf
See Docker image for image variants, tags, and more usage examples.
Installing packages¶
Using pip¶
To install Kopf using pip (assuming you have a virtualenv activated):
pip install kopf
Using uv¶
If you use uv, once you are ready to build a project, add Kopf as a dependency:
uv add kopf
Cluster preparation¶
Unless you use the standalone mode, create a few Kopf-specific custom resources in the cluster. These are used to coordinate several instances of Kopf-based operators so that they do not double-process the same resources — only one operator will be active at a time:
kubectl apply -f https://github.com/nolar/kopf/raw/main/peering.yaml
Depending on the security rules of your cluster, you might need RBAC resources applied, too (cluster- and user-specific; not covered here).
Example operators¶
To run the example operators or the code snippets from the documentation,
apply this CRD for kopf.dev/v1/kopfexamples. The examples will not operate
without it, but your own operator with your own resources does not need it:
kubectl apply -f https://github.com/nolar/kopf/raw/main/examples/crd.yaml
You are ready to go. Run an operator using pip and virtualenv:
kopf --help
kopf run --help
kopf run examples/01-minimal/example.py
Using uv:
uv run kopf --help
uv run kopf run --help
uv run kopf run examples/01-minimal/example.py
Extras¶
To minimize the disk footprint of Kopf projects, some heavy dependencies are omitted by default. You can add them as extras if you need them.
full-auth¶
If you use a managed Kubernetes service that requires sophisticated
authentication beyond plain username+password, fixed tokens,
or client SSL certificates, add the full-auth extra with Kubernetes clients,
which include those sophisticated authentication methods
(also see authentication piggy-backing):
pip install 'kopf[full-auth]'
uv add 'kopf[full-auth]'
uvx --from 'kopf[full-auth]' kopf run -v examples/01-minimal/example.py
uvloop¶
If you want extra I/O performance, install the uvloop extra (also see Custom event loops). It will be activated automatically when installed; no extra flags or configuration are needed:
pip install 'kopf[uvloop]'
uv add 'kopf[uvloop]'
uvx --from 'kopf[uvloop]' kopf run -v examples/01-minimal/example.py
dev¶
If you want mutating/validating webhooks (also see Admission control)
with self-signed certificates and/or ngrok tunneling,
install with the dev extra:
pip install 'kopf[dev]'
uv add 'kopf[dev]'
uvx --from 'kopf[dev]' kopf run -v examples/01-minimal/example.py
Warning
Self-signed certificates are unsafe for production environments. Ngrok tunnelling is not needed in production environments. This extra is intended for development environments only. Hence the name.
Note
This is the dev extra, not the dev dependency group.
The dependency groups are available only when installing Kopf from source.