Dagger Python SDK

A client package for running Dagger pipelines.

What is the Dagger Python SDK?

The Dagger Python SDK contains everything you need to develop CI/CD pipelines in Python, and run them on any OCI-compatible container runtime.

Requirements

• Python 3.10 or later
• Docker, or another OCI-compatible container runtime

A compatible version of the Dagger CLI is automatically downloaded and run by the SDK for you, although it’s possible to manage it manually.

Installation

From PyPI, using pip:

pip install dagger-io

You can also install via Conda, from the conda-forge channel:

conda install dagger-io

Example

Create a main.py file:

import sys

import anyio
import dagger
from dagger import dag


async def main(args: list[str]):
    async with dagger.connection():
        # build container with cowsay entrypoint
        ctr = (
            dag.container()
            .from_("python:alpine")
            .with_exec(["pip", "install", "cowsay"])
        )

        # run cowsay with requested message
        result = await ctr.with_exec(["cowsay", *args]).stdout()

    print(result)


anyio.run(main, sys.argv[1:])

Run with:

$ python main.py "Simple is better than complex"
  _____________________________
| Simple is better than complex |
  =============================
                             \
                              \
                                ^__^
                                (oo)\_______
                                (__)\       )\/\
                                    ||----w |
                                    ||     ||

Note It may take a while for it to finish, especially on first run with cold cache.

If you need to debug, you can stream the logs from the engine with the log_output config:

config = dagger.Config(log_output=sys.stderr)
async with dagger.connection(config):
    ...

Learn more

• Documentation
• API Reference
• Source code

Development

The SDK is managed with a Dagger module in ./dev. To see which tasks are available run:

dagger call -m dev

Common tasks

Run pytest in supported Python versions:

dagger call -m dev test default

Check for linting violations:

dagger call -m dev lint

Re-format code following common styling conventions:

dagger call -m dev format export --path=.

Update pinned development dependencies (run from this directory, ./sdk/python, or adjust export path accordingly):

dagger call -m ../../.dagger/modules/python-client-dev dev-container with-exec --args uv,lock,-U directory --path . export --path .

Update a single pinned development dependency (run from this directory, ./sdk/python, or adjust export path accordingly):

dagger call -m ../../.dagger/modules/python-client-dev dev-container with-exec --args uv,lock,-P,<DEPNAME> directory --path . export --path .

Build and preview the reference documentation:

dagger call -m dev docs preview up

Add --help to any command to check all the available options.