A Python library for Juju

Warning

python-libjuju is deprecated.

Charms should migrate to Jubilant, Canonical's recommended library for Juju integration tests. See How to migrate integration tests from pytest-operator.

Source code: https://github.com/juju/python-libjuju

Bug reports: https://github.com/juju/python-libjuju/issues

Documentation: https://pythonlibjuju.readthedocs.io/en/latest/

Supported Python versions: 3.8 through 3.13

Supported Juju versions: 3.1 through 3.6

Newest supported Ubuntu base: 24.04 LTS

Design Notes

• Asynchronous - Uses asyncio and async/await features of Python
• Websocket-level bindings are programmatically generated (indirectly) from the Juju golang code, ensuring full api coverage
• Provides an OO layer which encapsulates much of the websocket api and provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(), etc.)

Installation

pip3 install juju

Quickstart

Here's a simple example that shows basic usage of the library. The example connects to the currently active Juju model, deploys a single unit of the ubuntu charm, then exits:

Note : Pylibjuju requires an already bootstrapped Juju controller to connect to.

#!/usr/bin/python3importasyncioimportloggingimportsysfromjuju.modelimportModelasyncdefdeploy():
# Create a Model instance. We need to connect our Model to a Juju api# server before we can use it.model=Model()
# Connect to the currently active Juju modelawaitmodel.connect()
try:
# Deploy a single unit of the ubuntu charm, using the latest revision# from the stable channel of the Charm Store.ubuntu_app=awaitmodel.deploy(
'ubuntu',
application_name='my-ubuntu',
)
if'--wait'insys.argv:
# optionally block until the application is readyawaitmodel.wait_for_idle(status='active')
finally:
# Disconnect from the api server and cleanup.awaitmodel.disconnect()
defmain():
logging.basicConfig(level=logging.INFO)
# If you want to see everything sent over the wire, set this to DEBUG.ws_logger=logging.getLogger('websockets.protocol')
ws_logger.setLevel(logging.INFO)
# Run the deploy coroutine in an asyncio event loop, using a helper# that abstracts loop creation and teardown.asyncio.run(deploy())
if__name__=='__main__':
main()

More examples can be found in the docs, as well as in the examples/ directory of the source tree which can be run using tox. For example, to run examples/connect_current_model.py, use:

tox -e example -- examples/connect_current_model.py

REPL

To experiment with the library in a REPL, launch python in asyncio mode

$ python3 -m asyncio

and then, to connect to the current model and fetch status:

>>> from juju.model import Model
>>> model = Model()
>>> await model.connect_current()
>>> status = await model.get_status()

Versioning

The current Pylibjuju release policy tracks the Juju release cadence. In particular, whenever Juju makes a latest/stable release, pylibjuju pushes out a release with the same version in the following week. Newly generated schemas will be updated per Juju releases.