Install CrewAI 1.15.20 for Role Based AI Agents

Here’s the weird part nobody puts on the homepage: installing CrewAI for role based AI agents leaves you with two CrewAIs on one machine – a global CLI tool and a project virtualenv – and they upgrade on different clocks. I burned an evening “upgrading” with crewai install while the lockfile quietly kept last month’s runtime.

CrewAI is the open-source Python framework for role-playing agent teams (role + goal + backstory per agent). This is the deploy path for 1.15.20 (stable release dated Sep 4, 2026 per GitHub), not another researcher-writer walkthrough. Package page: PyPI crewai. Tag notes: 1.15.20 release (legacy platform tool alias discovery fix).

System requirements before you touch the CLI

Python >=3.10 and <3.14 – full stop. 3.14 is out of range; stay on 3.10-3.13. That constraint is from the official installation docs (and PyPI), not folklore.

RAM band above is practical community guidance for laptop crews on cloud APIs – not a hard vendor SLA. Cluster/K8s installs are a different budget entirely.

Official download / install source

Skip random zips. Supported inputs:

• PyPI: pypi.org/project/crewai (1.15.20 wheel/sdist as of the Sep 4, 2026 tag)
• Docs: docs.crewai.com/en/installation
• Repo/releases: github.com/crewAIInc/crewAI

Current docs lead with uv (Astral) for the CLI tool and project deps. Older posts still show plain pip install crewai; treat those as stale unless you know why you need pip.

Install CrewAI 1.15.20 step by step

Check the interpreter first:

python3 --version
# need 3.10.x-3.13.x

1. Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or without curl
wget -qO- https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

New terminal after that. PATH has to see ~/.local/bin (Windows: %USERPROFILE%.localbin).

2. Global CrewAI CLI

uv tool install crewai
# PATH warning?
uv tool update-shell

That pulls current stable from PyPI – 1.15.20 as of the Sep 4, 2026 release. Want a freeze?

uv tool install crewai==1.15.20

3. Confirm the tool

uv tool list
crewai version
# or: crewai --version

You want a crewai entry and a version line you trust from the CLI itself, not from a blog screenshot.

Windows tip before the first heavy resolve: if native builds have burned you before, install Visual Studio Build Tools with Desktop development with C++ first. chromadb pulls chroma-hnswlib; missing headers show up fast.

First-time configuration for a role-based crew

Default scaffold is JSON-first now – agents/*.jsonc plus crew.jsonc. Old YAML/crew.py tutorials look “broken” until you pass --classic.

crewai create crew role_agents_demo
cd role_agents_demo

# only if you need 2024-2025 layout:
# crewai create crew role_agents_demo --classic

Bare minimum:

1. Provider keys in .env (e.g. OPENAI_API_KEY=...). Add SERPER_API_KEY only if a template agent actually searches the web.
2. Edit agents/*.jsonc so each agent has a clear role, goal, and backstory – what you came for with role based AI agents.
3. Task order / process / default inputs live in crew.jsonc.
4. Then:

crewai install
crewai run

Extra packages: uv add <package>. Supply-chain wrinkle from the install docs: CrewAI internal packages set exclude-newer = "3 days", so a transitive release from yesterday may not resolve until you pin it yourself.

Verify the install actually works

Three layers – don’t stop at the first green line:

# A) Global CLI
crewai version
uv tool list

# B) Project directory - runtime agents actually import
uv pip show crewai

# C) Smoke run
crewai run

A successful run streams agent steps in the terminal. If A and B disagree on version, jump to the upgrade section – kickoff always uses the project venv.

Common install errors and fixes

chroma-hnswlib / MSVC on Windows. Classic text: Failed to build chroma-hnswlib or fatal error C1083: Cannot open include file: 'float.h'. Install Build Tools + C++ desktop workload (Windows SDK if headers still vanish), restart the shell, re-run uv tool install crewai. Official install docs call this out; community threads match.

crewai not found. PATH. uv tool update-shell, new terminal, or prepend uv’s bin dir. Still missing? uv tool uninstall crewai then uv tool install crewai --force.

Python 3.14 / wrong interpreter. Constraint is >=3.10,<3.14. Point uv at a supported interpreter before the project venv exists.

Upgrade path and clean uninstall

The catch is in the upgrading guide: CLI and project are separate products that share a name.

# Global CLI only
uv tool install crewai --upgrade
# optional pin:
# uv tool install crewai==1.15.20 --force

# Project runtime (from project root) - THIS is what agents execute
uv add "crewai[tools]>=1.15.20"
crewai install
uv pip show crewai

crewai install alone does not raise the version. It wraps a lockfile sync (uv sync territory). You can feel productive and still run old code. After big jumps, re-check tool imports and any custom memory/embedder settings.

Uninstall the global tool:

uv tool uninstall crewai

Delete the project folder (and its .venv) for local cleanup. Tear down uv itself only if you’re done with the whole toolchain (uv cache clean plus binaries under ~/.local/bin).

FAQ

Do I need Docker to run role based AI agents with CrewAI?

No. Local uv + CLI is the documented default. Docker is optional packaging for servers.

Why does crewai version disagree with uv pip show crewai?

Different installs. Example: CLI shows 1.15.20 after uv tool install crewai --upgrade, project still locks 1.14.x until uv add "crewai[tools]>=1.15.20" and crewai install. Kickoff reads the project venv every time – treat the two strings as unrelated products.

Should new projects use JSON crews or --classic YAML?

JSON-first (agents/*.jsonc + crew.jsonc) unless you’re glued to an old YAML tutorial or an existing crew.py + config/agents.yaml standard. Then --classic.

Open a terminal, run uv tool install crewai, scaffold with crewai create crew role_agents_demo, drop your API key in .env, then crewai install && crewai run – first role-based crew should be live before the coffee cools.