CrewAI Tutorial (Python): deploying with Docker for beginners

This tutorial shows you how to package a basic CrewAI Python project into a Docker image and run it consistently on any machine. You need this when your local Python environment works but you want the same agent setup to run in CI, on a server, or inside a container without dependency drift.

What You'll Need

• •Python 3.10 or 3.11
• •Docker Desktop or Docker Engine installed
• •A CrewAI project with:
  • •crewai
  • •crewai-tools
  • •python-dotenv
• •An LLM API key, such as:
  • •OPENAI_API_KEY
• •Basic files in your project:
  • •main.py
  • •.env
  • •requirements.txt
  • •Dockerfile
  • •.dockerignore

Step-by-Step

1. •Start with a minimal CrewAI app that runs locally. Keep the agent and task simple so you can confirm Docker is not the problem before adding complexity.

from crewai import Agent, Task, Crew, Process
from dotenv import load_dotenv

load_dotenv()

researcher = Agent(
    role="Researcher",
    goal="Find concise facts about Dockerizing Python apps",
    backstory="You write practical deployment notes for developers.",
    verbose=True,
)

task = Task(
    description="Explain one reason to use Docker for Python deployments.",
    expected_output="A short practical explanation.",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.sequential,
)

if __name__ == "__main__":
    result = crew.kickoff()
    print(result)

2. •Add your dependencies and environment variables. The key detail here is that Docker will install packages from requirements.txt, then read runtime config from environment variables passed at container start.

crewai
crewai-tools
python-dotenv

OPENAI_API_KEY=your_api_key_here

3. •Create a Dockerfile that installs your dependencies and runs the app. Use a slim Python base image, copy only what you need, and make the container execute main.py directly.

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "main.py"]

4. •Add a .dockerignore file so you do not send unnecessary files into the build context. This keeps builds smaller and avoids accidentally copying local caches or secrets.

__pycache__
*.pyc
*.pyo
*.pyd
.env
.git
.gitignore
venv
.venv
dist
build
.DS_Store

5. •Build the image and run the container with your API key passed in at runtime. This is the part beginners usually miss: the container does not automatically inherit your local shell environment unless you pass it explicitly.

docker build -t crewai-docker-demo .
docker run --rm \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  crewai-docker-demo

6. •If you want a cleaner setup for local development and deployment, use Compose. This makes it easier to add more environment variables later without rewriting long docker run commands.

services:
  app:
    build: .
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}

Run it with:

docker compose up --build

Testing It

When it works, you should see CrewAI logging from the agent and then a final task result printed to stdout. If the container exits immediately with an authentication error, check that OPENAI_API_KEY is set in your shell before running Docker.

If you get an import error, verify that requirements.txt includes every package used by your script and that the Docker build completed without errors. If the model response is empty or hangs, confirm your network access and that your chosen model/provider is valid for your account.

A good sanity check is to delete your local virtual environment and rerun only the Docker command. If the app still works inside Docker, you have isolated it from machine-specific Python issues.

Next Steps

• •Add tool usage with crewai-tools, such as web search or file reading.
• •Split agents and tasks into separate modules once the single-file version is stable.
• •Add health checks and logging before deploying this into Kubernetes or a cloud container service

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.