{"id":4688,"library":"prefect-docker","title":"Prefect Docker","description":"The `prefect-docker` library provides Prefect integrations for orchestrating flow runs within Docker containers. It includes infrastructure blocks for defining Docker execution environments and workers for managing Docker-based work pools. This library is specifically designed for Prefect 2.x and later. The current version is 0.7.1, with releases typically aligning with new features or compatibility updates for the core Prefect library.","status":"active","version":"0.7.1","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect/tree/main/src/integrations/prefect-docker","tags":["prefect","docker","orchestration","workflow","containerization"],"install":[{"cmd":"pip install prefect-docker","lang":"bash","label":"Install prefect-docker"}],"dependencies":[{"reason":"Core Prefect library for defining and orchestrating flows.","package":"prefect"},{"reason":"Python client for interacting with the Docker daemon, used by prefect-docker.","package":"docker"}],"imports":[{"note":"DockerContainer is part of the prefect-docker collection, not the core Prefect library directly. Ensure `prefect_docker` is imported.","wrong":"from prefect.infrastructure import DockerContainer","symbol":"DockerContainer","correct":"from prefect_docker.infrastructure import DockerContainer"},{"symbol":"DockerWorker","correct":"from prefect_docker.workers import DockerWorker"},{"note":"This specific deployment object is located in `prefect_docker.deployments`, not `prefect_docker.infrastructure`.","wrong":"from prefect_docker.infrastructure import DockerContainerDeployment","symbol":"DockerContainerDeployment","correct":"from prefect_docker.deployments import DockerContainerDeployment"}],"quickstart":{"code":"from prefect import flow\nfrom prefect_docker.infrastructure import DockerContainer\n\n@flow(log_prints=True)\ndef hello_docker_flow(name: str = \"World\"):\n    \"\"\"A simple flow that prints a greeting.\"\"\"\n    print(f\"Hello, {name} from a Docker container!\")\n\nif __name__ == \"__main__\":\n    # Define a DockerContainer infrastructure block.\n    # This block specifies how your flow runs will be executed in Docker.\n    docker_infra = DockerContainer(\n        image=\"python:3.10-slim-buster\", # Use a small, readily available image\n        # You can also specify other Docker options like network, volumes, env, etc.\n    )\n\n    # For a quick local test without full Prefect deployment,\n    # you can directly apply the infrastructure to the flow.\n    # Ensure your Docker daemon is running.\n    print(\"Running flow locally using DockerContainer infrastructure...\")\n    hello_docker_flow.with_options(infrastructure=docker_infra)(\"TestUser\")\n    print(\"Flow run completed.\")\n\n    # For full Prefect deployment, you would typically save the block:\n    # import asyncio\n    # asyncio.run(docker_infra.save(\"my-docker-infra-block\", overwrite=True))\n    # Then deploy via CLI: `prefect deploy --name \"my-flow\" --infra-block docker-container/my-docker-infra-block`","lang":"python","description":"This quickstart demonstrates how to define a Prefect flow and configure it to run within a Docker container using the `DockerContainer` infrastructure block. It includes a runnable example that executes the flow locally using the specified Docker image. For full deployment, the infrastructure block would typically be saved and referenced in a Prefect deployment."},"warnings":[{"fix":"Rewrite execution configuration to use Prefect 2.x infrastructure concepts like `DockerContainer` blocks and `DockerWorker`s.","message":"Prefect 1.x used `DockerExecutor`, while Prefect 2.x uses `DockerContainer` for infrastructure and `DockerWorker` for work pool agents. Code written for Prefect 1.x's Docker execution will not work with `prefect-docker`.","severity":"breaking","affected_versions":"All versions of prefect-docker (designed for Prefect 2.x+)"},{"fix":"Ensure Docker Desktop is running or the Docker service is active on your host. On Linux, ensure your user is part of the `docker` group (`sudo usermod -aG docker $USER`) and reboot or re-login.","message":"The Docker daemon must be running and accessible for `prefect-docker` to function. If the daemon is not active or the user lacks permissions, flow runs will fail to start.","severity":"gotcha","affected_versions":"All versions"},{"fix":"`DockerContainer` should be used when defining a specific Docker environment for a deployment. `DockerWorker` should be used when running an agent to poll a work pool for runs configured to use Docker infrastructure.","message":"Confusing `DockerContainer` (an infrastructure block) with `DockerWorker` (an agent that pulls work from a work pool). `DockerContainer` defines *how* a flow run executes; `DockerWorker` is the process that *starts* those `DockerContainer` instances.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure containers can resolve the Prefect API URL. This often involves configuring Docker container networks, passing `PREFECT_API_URL` correctly, or ensuring the API server is exposed on a public IP/hostname if not running locally.","message":"Networking issues can prevent Docker containers from reaching the Prefect API server, especially if running the server and containers on different networks or hosts.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}