The ops library
The ops library is a Python framework for developing and testing Kubernetes and machine charms. While charms can be written in any language, ops defines the latest standard, and charmers are encouraged to use Python with ops for all charms. The library is an official component of the Charm SDK, itself a part of the Juju universe.
opsis available on PyPI.- The latest version of
opsrequires Python 3.10 or above.- Read our docs for tutorials, how-to guides, the library reference, and more.
Give it a try
Let's use ops to build a Kubernetes charm:
Set up
See Juju | Set things up.
Choose the automatic track and MicroK8s.
Write your charm
On your Multipass VM, create a charm directory and use Charmcraft to initialise your charm file structure:
mkdir ops-example
cd ops-example
charmcraft init
This has created a standard charm directory structure:
$ ls -R
.:
CONTRIBUTING.md README.md pyproject.toml src tox.ini
LICENSE charmcraft.yaml requirements.txt tests
./src:
charm.py
./tests:
integration unit
./tests/integration:
test_charm.py
./tests/unit:
test_charm.py
Things to note:
-
The
charmcraft.yamlfile shows that what we have is an example charm calledops-example, which uses an OCI image resourcehttpbinfromkennethreitz/httpbin. -
The
requirements.txtfile lists the version ofopsto use. -
The
src/charm.pyfile importsopsand usesopsconstructs to create a charm classOpsExampleCharm, observe Juju events, and pair them to event handlers:
import ops
class OpsExampleCharm(ops.CharmBase):
"""Charm the service."""
def __init__(self, *args):
super().__init__(*args)
self.framework.observe(self.on['httpbin'].pebble_ready, self._on_httpbin_pebble_ready)
self.framework.observe(self.on.config_changed, self._on_config_changed)
def _on_httpbin_pebble_ready(self, event: ops.PebbleReadyEvent):
"""Define and start a workload using the Pebble API.
Change this example to suit your needs. You'll need to specify the right entrypoint and
environment configuration for your specific workload.
Learn more about interacting with Pebble at
https://canonical.com/juju/docs/ops/latest/reference/pebble/
"""
# Get a reference the container attribute on the PebbleReadyEvent
container = event.workload
# Add initial Pebble config layer using the Pebble API
container.add_layer('httpbin', self._pebble_layer, combine=True)
# Make Pebble reevaluate its plan, ensuring any services are started if enabled.
container.replan()
# Learn more about statuses at
# https://documentation.ubuntu.com/juju/3.6/reference/status/
self.unit.status = ops.ActiveStatus()
See more:
ops.PebbleReadyEvent
- The
tests/unit/test_charm.pyfile importsops.testingand uses it to set up a unit test:
import ops
from ops import testing
from charm import OpsExampleCharm
def test_httpbin_pebble_ready():
# Arrange:
ctx = testing.Context(OpsExampleCharm)
container = testing.Container('httpbin', can_connect=True)
state_in = testing.State(containers={container})
# Act:
state_out = ctx.run(ctx.on.pebble_ready(container), state_in)
# Assert:
updated_plan = state_out.get_container(container.name).plan
expected_plan = {
'services': {
'httpbin': {
'override': 'replace',
'summary': 'httpbin',
'command': 'gunicorn -b 0.0.0.0:80 httpbin:app -k gevent',
'startup': 'enabled',
'environment': {'GUNICORN_CMD_ARGS': '--log-level info'},
}
},
}
assert expected_plan == updated_plan
assert (
state_out.get_container(container.name).service_statuses['httpbin']
== ops.pebble.ServiceStatus.ACTIVE
)
assert state_out.unit_status == testing.ActiveStatus()
See more:
ops.testing
Explore further, start editing the files, or skip ahead and pack the charm:
charmcraft pack
If you didn't take any wrong turn or simply left the charm exactly as it was, this has created a file called ops-example_ubuntu-22.04-amd64.charm (the architecture bit may be different depending on your system's architecture). Use this name and the resource from the metadata.yaml to deploy your example charm to your local MicroK8s cloud:
juju deploy ./ops-example_ubuntu-22.04-amd64.charm --resource httpbin-image=kennethreitz/httpbin
Congratulations, you’ve just built your first Kubernetes charm using ops!
Clean up
See Juju | Tear things down.
Choose the automatic track.
Next steps
- Read the docs.
- Read our Code of conduct and join our chat and forum or open an issue.
- Read our CONTRIBUTING guide and contribute!
4 maintainers
Metadata
4 maintainers
Release files for ops 3.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ops-3.8.2.tar.gz | 610.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ops-3.8.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 826.5 kB
Release files / ops-3.8.2.tar.gz
| Download URL | ops-3.8.2.tar.gz |
|---|---|
| Size | 610.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a516e76a76fdfd4a37f26f2b9956c332b56bda72014c8565ceb4f6deb137407f
|
|
BLAKE2b-256 checksum How to use checksums |
850a6e5730c50c1737b505ccd0d7bc3c53c625745a75aae9faa2fe635ea7a473
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 31, 2026.
Transparency logRelease files / ops-3.8.2-py3-none-any.whl
| Download URL | ops-3.8.2-py3-none-any.whl |
|---|---|
| Size | 215.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dcead2241d17921441123425072dd6adddf5f337dc6d6fd2b3ba1fd60a0af822
|
|
BLAKE2b-256 checksum How to use checksums |
f04cddaef2a0f8d208aed071087b61e6984bb8507cf202c965025446cf4cce8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 31, 2026.
Transparency log
