Dagger.io Python SDK

0.20.6 verified Mon Apr 27 auth: no python

A Python client for running Dagger CI/CD pipelines. Provides a programmable engine for containerized workflows. Current version: 0.20.6. Release cadence: frequent, often weekly.

pip install dagger-io

Common errors

error grpc.FutureTimeoutError: Dagger engine not reachable ↓

cause Dagger engine is not running or not accessible.

fix

Ensure Dagger CLI is installed and run 'dagger session' or 'dagger run' before executing the script.

error ImportError: cannot import name 'Connection' from 'dagger' ↓

cause Outdated or wrong installation (e.g., installed 'dagger' instead of 'dagger-io').

fix

Uninstall the wrong package: pip uninstall dagger and install dagger-io: pip install dagger-io

error RuntimeError: This event loop is already running ↓

cause Trying to run async code in a non-async main or within an already running loop.

fix

Use asyncio.run(main()) in the script entry point.

Warnings

breaking Python SDK requires Python >=3.10. Older Python versions will cause import or runtime errors. ↓

fix Ensure your Python version is 3.10 or later.

gotcha The Dagger engine must be running (via 'dagger run' or 'dagger session') before using the SDK. If not, you'll get a connection error. ↓

fix Start the Dagger CLI or use 'dagger run' to execute your Python script.

gotcha All methods that interact with the engine (e.g., container().from_()) are async. Forgetting 'await' or not running inside an async context will cause RuntimeError or infinite hang. ↓

fix Use 'async with dagger.Connection() as client' and await all coroutines.

Imports

dagger
```
import dagger
```
The correct import is simply 'import dagger'.
Connection
```
from dagger import Connection
```
Connection is the main entrypoint for executing pipelines.
Client
```
from dagger import Client
```
Client is used within Connection context to interact with the Dagger engine.

Quickstart

Minimal example: connects to Dagger engine, runs 'python -V' in a container, prints version.

import dagger

async def main():
    async with dagger.Connection() as client:
        python = (
            client.container()
            .from_("python:3.11-slim")
            .with_exec(["python", "-V"])
        )
        version = await python.stdout()
        print(f"Python version: {version}")

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())