installation.mdx

title	description	icon
Installation	Get started with CrewAI - Install, configure, and build your first AI crew	wrench

**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.

Choose your preferred method to create a virtual environment:

    **Using venv (Python's built-in tool):**
    ```shell Terminal
    python3 -m venv .venv
    ```

    **Using conda:**
    ```shell Terminal
    conda create -n crewai-env python=3.12
    ```
</Step>

<Step title="Activate the Virtual Environment">
    Activate your virtual environment based on your platform:

    **On macOS/Linux (venv):**
    ```shell Terminal
    source .venv/bin/activate
    ```

    **On Windows (venv):**
    ```shell Terminal
    .venv\Scripts\activate
    ```

    **Using conda (all platforms):**
    ```shell Terminal
    conda activate crewai-env
    ```
</Step>

Installing CrewAI

Now let's get you set up! 🚀

Install CrewAI with all recommended tools using either method: ```shell Terminal pip install 'crewai[tools]' ``` or ```shell Terminal pip install crewai crewai-tools ```

    <Note>
      Both methods install the core package and additional tools needed for most use cases.
    </Note>
</Step>

<Step title="Upgrade CrewAI (Existing Installations Only)">
    If you have an older version of CrewAI installed, you can upgrade it:
    ```shell Terminal
    pip install --upgrade crewai crewai-tools
    ```

    <Warning>
        If you see a Poetry-related warning, you'll need to migrate to our new dependency manager:
        ```shell Terminal
        crewai update
        ```
        This will update your project to use [UV](https://github.com/astral-sh/uv), our new faster dependency manager.
    </Warning>

    <Note>
        Skip this step if you're doing a fresh installation.
    </Note>
</Step>

<Step title="Verify Installation">
    Check your installed versions:
    ```shell Terminal
    pip freeze | grep crewai
    ```

    You should see something like:
    ```markdown Output
    crewai==X.X.X
    crewai-tools==X.X.X
    ```
    <Check>Installation successful! You're ready to create your first crew.</Check>
</Step>

Creating a New Project

We recommend using the YAML Template scaffolding for a structured approach to defining agents and tasks. Run the CrewAI CLI command: ```shell Terminal crewai create crew ```

This creates a new project with the following structure:
<Frame>
```
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
```
</Frame>

You can install additional tools using UV: ```shell Terminal uv add ```

<Tip>
  UV is our preferred package manager as it's significantly faster than pip and provides better dependency resolution.
</Tip>

Your project will contain these essential files:

| File | Purpose |
| --- | --- |
| `agents.yaml` | Define your AI agents and their roles |
| `tasks.yaml` | Set up agent tasks and workflows |
| `.env` | Store API keys and environment variables |
| `main.py` | Project entry point and execution flow |
| `crew.py` | Crew orchestration and coordination |
| `tools/` | Directory for custom agent tools |

<Tip>
  Start by editing `agents.yaml` and `tasks.yaml` to define your crew's behavior.
  Keep sensitive information like API keys in `.env`.
</Tip>

Next Steps

Follow our quickstart guide to create your first CrewAI agent and get hands-on experience. Connect with other developers, get help, and share your CrewAI experiences.