Python Version Requirements

CrewAI requires Python >=3.10 and <3.13. Here’s how to check your version:

python3 --version

If you need to update Python, visit python.org/downloads

Setting Up Your Environment

Before installing CrewAI, it’s recommended to set up a virtual environment. This helps isolate your project dependencies and avoid conflicts.

1

Create a Virtual Environment

Choose your preferred method to create a virtual environment:

Using venv (Python’s built-in tool):

Terminal
python3 -m venv .venv

Using conda:

Terminal
conda create -n crewai-env python=3.12
2

Activate the Virtual Environment

Activate your virtual environment based on your platform:

On macOS/Linux (venv):

Terminal
source .venv/bin/activate

On Windows (venv):

Terminal
.venv\Scripts\activate

Using conda (all platforms):

Terminal
conda activate crewai-env

Installing CrewAI

Now let’s get you set up! πŸš€

1

Install CrewAI

Install CrewAI with all recommended tools using either method:

Terminal
pip install 'crewai[tools]'

or

Terminal
pip install crewai crewai-tools

Both methods install the core package and additional tools needed for most use cases.

2

Upgrade CrewAI (Existing Installations Only)

If you have an older version of CrewAI installed, you can upgrade it:

Terminal
pip install --upgrade crewai crewai-tools

If you see a Poetry-related warning, you’ll need to migrate to our new dependency manager:

Terminal
crewai update

This will update your project to use UV, our new faster dependency manager.

Skip this step if you’re doing a fresh installation.

3

Verify Installation

Check your installed versions:

Terminal
pip freeze | grep crewai

You should see something like:

Output
crewai==X.X.X
crewai-tools==X.X.X
Installation successful! You’re ready to create your first crew.

Creating a New Project

We recommend using the YAML Template scaffolding for a structured approach to defining agents and tasks.

1

Generate Project Structure

Run the CrewAI CLI command:

Terminal
crewai create crew <project_name>

This creates a new project with the following structure:

my_project/
β”œβ”€β”€ .gitignore
β”œβ”€β”€ pyproject.toml
β”œβ”€β”€ README.md
β”œβ”€β”€ .env
└── src/
    └── my_project/
        β”œβ”€β”€ __init__.py
        β”œβ”€β”€ main.py
        β”œβ”€β”€ crew.py
        β”œβ”€β”€ tools/
        β”‚   β”œβ”€β”€ custom_tool.py
        β”‚   └── __init__.py
        └── config/
            β”œβ”€β”€ agents.yaml
            └── tasks.yaml
2

Install Additional Tools

You can install additional tools using UV:

Terminal
uv add <tool-name>

UV is our preferred package manager as it’s significantly faster than pip and provides better dependency resolution.

3

Customize Your Project

Your project will contain these essential files:

FilePurpose
agents.yamlDefine your AI agents and their roles
tasks.yamlSet up agent tasks and workflows
.envStore API keys and environment variables
main.pyProject entry point and execution flow
crew.pyCrew orchestration and coordination
tools/Directory for custom agent tools

Start by editing agents.yaml and tasks.yaml to define your crew’s behavior. Keep sensitive information like API keys in .env.

Next Steps