Preparare il computer
6Installare CrewAI passo passo
Installi uv e CrewAI su Windows, macOS o Linux seguendo la documentazione ufficiale, risolvi i problemi più comuni e lanci il primo script di prova con uv run.
Ora che conosci gli attrezzi, è il momento di metterli sul banco. L'installazione di CrewAI è come montare una cucina nuova: si parte dall'impianto (uv), poi si collegano gli elettrodomestici (CrewAI), infine si accende un fornello per vedere che tutto funzioni. Seguiamo passo passo la pagina di installazione ufficiale, verificata su CrewAI 1.15.21.
Alla fine del capitolo avrai due cose: il comando crewai pronto nel Terminale: Finestra in cui si scrivono comandi testuali al computer invece di cliccare. Su Windows si chiama PowerShell o Prompt dei comandi, su macOS e Linux Terminale. glossario e un piccolo Script: Un file di codice che si esegue dall'inizio alla fine con un solo comando, per esempio uv run primo_crew.py. glossario di prova che dimostra che il tuo computer sa eseguire CrewAI. Tieni a portata di mano il terminale aperto nella Cartella di progetto: La cartella del computer che contiene tutti i file di un tuo lavoro. I comandi si lanciano stando "dentro" questa cartella. glossario corso-crewai che hai creato nel capitolo 5.
Le due strade#
Con uv: Programma gratuito che installa Python e i pacchetti in modo rapido e ordinato. È lo strumento consigliato dalla documentazione di CrewAI. glossario installato, CrewAI si può usare in due modi, e in questo capitolo li prepari entrambi.
- La CLI di CrewAI, installata una volta per tutte con
uv tool install crewai. Una CLI: Command Line Interface: un programma che si usa dal terminale con comandi. CrewAI ne ha una:crewai create,crewai run… glossario (Command Line Interface) è un programma che si usa dal terminale con comandi: qui il comando si chiamacrewaie serve a creare e avviare progetti completi, con molti file. La userai nel capitolo 14. - Lo script eseguito con
uv run: un solo file che dichiara in testa di cosa ha bisogno. uv prepara da solo l'ambiente e lo esegue. È il metodo che il corso usa in tutti gli esempi, perché ogni esempio sta in un file che puoi copiare e lanciare.
Passo 1: installare uv#
Il comando ufficiale scarica il programma di installazione di uv dal sito di Astral e lo esegue. Su macOS e Linux:
# scarica l'installatore di uv con curl e lo esegue
curl -LsSf https://astral.sh/uv/install.sh | shSolo se il terminale risponde che curl non esiste, usa al suo posto wget -qO- https://astral.sh/uv/install.sh | sh.
Su Windows, in PowerShell:
# scarica ed esegue l'installatore di uv per Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"L'installazione dura pochi secondi. Poi chiudi il terminale e riaprilo: il terminale legge l'elenco dei programmi disponibili solo quando si apre. Controlla che uv risponda chiedendogli la versione. Il comando è uguale su tutti i sistemi; qui e nel resto del corso lo trovi comunque in due riquadri, uno per macOS e Linux e uno per Windows.
uv --versionuv --versionSul computer usato per preparare il corso la risposta è questa (esempio reale; il tuo numero di versione sarà probabilmente più recente):
uv 0.11.30 (x86_64-unknown-linux-gnu)Quel | nel comando si chiama «pipe» e passa il risultato del primo comando al secondo: curl scarica un file, sh lo esegue. Eseguire codice scaricato da internet è sicuro solo se ti fidi di chi lo pubblica: qui l'indirizzo è quello ufficiale indicato sia dalla documentazione di CrewAI sia da quella di uv.
Passo 2: installare la CLI di CrewAI#
Con uv pronto, un solo comando installa CrewAI come strumento disponibile in qualsiasi cartella:
# installa il comando crewai
uv tool install crewai# installa il comando crewai
uv tool install crewaiuv scarica CrewAI e le sue dipendenze e crea il comando crewai. Questo è l'output reale ottenuto su una macchina Linux di prova, accorciato: abbiamo tolto l'elenco dei 134 pacchetti installati e sostituito il percorso della cartella con uno d'esempio. I tempi sono bassi perché i pacchetti erano già stati scaricati: la prima volta ci vorrà di più.
Resolved 134 packages in 441ms
Installed 134 packages in 540ms
Installed 1 executable: crewai
warning: `/home/anna/.local/bin` is not on your PATH. To use installed tools, run `export PATH="/home/anna/.local/bin:$PATH"` or `uv tool update-shell`.L'ultima riga è un avviso che può capitare anche a te. Dice che la cartella in cui uv ha messo il comando crewai non è nel PATH: La variabile d'ambiente con l'elenco delle cartelle in cui il terminale cerca i programmi. Se la cartella di un programma non è nel PATH, il terminale risponde che il comando non esiste. glossario, l'elenco delle cartelle in cui il terminale cerca i programmi. Finché non la aggiungi, scrivendo crewai il terminale risponderà che il comando non esiste. La soluzione indicata dalla documentazione è:
# aggiunge la cartella degli strumenti di uv al PATH
uv tool update-shell# aggiunge la cartella degli strumenti di uv al PATH
uv tool update-shellPoi chiudi e riapri il terminale, di nuovo. Se non hai visto nessun avviso, salta questo passaggio.
Verifica#
Chiedi a CrewAI la sua versione. Il comando è uguale su tutti i sistemi:
crewai versioncrewai versioncrewai version: 1.15.21Se vedi crewai version: seguito da un numero, la CLI è installata. Il numero può essere più alto di 1.15.21 se nel frattempo è uscita una versione nuova: gli script del corso fissano comunque la 1.15.21, quindi funzioneranno lo stesso. Puoi vedere gli strumenti installati con uv anche con uv tool list.
La pagina ufficiale riporta gli stessi due comandi, uno sotto l'altro:
Cosa sa fare la CLI#
Ogni CLI ben fatta spiega se stessa: basta aggiungere --help. Ecco l'output reale di crewai --help con CrewAI 1.15.21.
Non ti servono tutti. Quelli che incontrerai nel corso sono pochi:
| Comando | A cosa serve | Dove lo vedi |
|---|---|---|
crewai version | Mostra la versione installata. | Questo capitolo |
crewai create crew nome --classic | Crea la cartella di un progetto completo con file già pronti. | Capitolo 14 |
crewai install | Installa le dipendenze del progetto (usa uv dietro le quinte). | Capitolo 14 |
crewai run | Avvia la crew o il flow del progetto. | Capitolo 14 |
crewai reset-memories | Cancella la memoria salvata dalle esecuzioni precedenti. | Capitolo 15 |
crewai login, crewai deploy | Collegano il progetto alla piattaforma commerciale CrewAI AMP (capitolo 4). | Solo citati: il corso non li usa |
Problemi frequenti#
Windows: errore su float.h#
La documentazione segnala un errore tipico di Windows durante l'installazione: un messaggio che nomina chroma-hnswlib e contiene fatal error C1083: Cannot open include file: 'float.h'. Significa che un pacchetto va compilato e al computer mancano gli strumenti per farlo. La soluzione ufficiale è installare i Visual Studio Build Tools di Microsoft, selezionando durante l'installazione il carico di lavoro Desktop development with C++ (sviluppo di applicazioni desktop in C++). Poi ripeti uv tool install crewai.
La versione di Python#
CrewAI 1.15.21 funziona con Python da 3.10 a 3.13; la 3.14 non è supportata. Di solito uv sceglie da solo una versione adatta. Se però ricevi errori che parlano della versione di Python, puoi chiedere a uv una versione precisa: l'opzione --python dice quale Python usare per l'ambiente dello strumento, e se manca uv la scarica.
# reinstalla la CLI usando Python 3.12
uv tool install crewai --python 3.12# reinstalla la CLI usando Python 3.12
uv tool install crewai --python 3.12Il comando crewai non viene trovato#
Quasi sempre è il PATH: esegui uv tool update-shell e riapri il terminale, come visto sopra. Se hai aperto il terminale incorporato di VS Code prima di installare, chiudi e riapri anche VS Code.
Aggiornare CrewAI#
CrewAI esce con versioni nuove spesso, a volte a pochi giorni di distanza. Per sapere qual è l'ultima puoi guardare la pagina del pacchetto su PyPI, il grande archivio pubblico dei pacchetti Python.
Per aggiornare la CLI:
# aggiorna il comando crewai all'ultima versione
uv tool install crewai --upgrade# aggiorna il comando crewai all'ultima versione
uv tool install crewai --upgradeAttenzione a cosa aggiorna: solo lo strumento globale crewai, non i progetti che hai già creato, che restano sulla loro versione finché non li aggiorni tu, come spiega la guida ufficiale all'aggiornamento. Anche gli script del corso restano sulla 1.15.21, perché la versione è scritta nella loro intestazione: è voluto, così un aggiornamento non rompe un esempio che funzionava.
La telemetria#
Molti programmi mandano ai loro sviluppatori dati anonimi su come vengono usati: è la Telemetria: Dati anonimi di utilizzo che un programma invia ai suoi sviluppatori. In CrewAI si disattiva con CREWAI_DISABLE_TELEMETRY=true. glossario. Secondo la pagina ufficiale, CrewAI raccoglie informazioni come le versioni di CrewAI e di Python, il sistema operativo, il numero di agenti e di task, il tipo di process, i nomi dei modelli e degli strumenti usati. Non raccoglie i testi dei tuoi prompt, a meno che tu non attivi esplicitamente l'opzione share_crew=True.
Se preferisci non inviare nulla, la documentazione indica un'impostazione con un nome, CREWAI_DISABLE_TELEMETRY, da mettere a true. Nel corso la scriviamo nel file delle impostazioni .env (lo spiega per bene il capitolo 7). Se vuoi impostarla solo per il terminale aperto, su macOS e Linux:
# vale fino alla chiusura di questo terminale
export CREWAI_DISABLE_TELEMETRY=trueE su Windows, in PowerShell:
# vale fino alla chiusura di questa finestra di PowerShell
$env:CREWAI_DISABLE_TELEMETRY = "true"La telemetria è una cosa diversa dal tracciamento delle esecuzioni offerto dalla piattaforma AMP. Al primo avvio di una crew CrewAI potrebbe chiederti «Would you like to view your execution traces?», cioè se vuoi vedere online il dettaglio dell'esecuzione: puoi rispondere di no. Ne riparleremo nel capitolo 17.
Il metodo del corso: uno script con uv run#
Ora la seconda strada, quella che userai negli esempi. Non richiede la CLI: basta uv. In corso-crewai crea con VS Code un file chiamato prova_crewai.py con questo contenuto. Lo script importa CrewAI e stampa la versione e il modello scritto nelle impostazioni.
# /// script
# requires-python = ">=3.10,<3.14"
# dependencies = ["crewai[tools]==1.15.21"]
# ///
"""Controlla che CrewAI si installi e legga il file .env."""
import os
import crewai
# Stampa la versione installata e il modello scritto nel file .env
print("crewai", crewai.__version__, "| MODEL da .env:", os.environ.get("MODEL"))Le righe tra # /// script e # /// sono il biglietto per uv:
requires-python = ">=3.10,<3.14": usa un Python dalla 3.10 alla 3.13.dependencies = ["crewai[tools]==1.15.21"]: installa CrewAI esattamente nella versione 1.15.21, con l'aggiunta[tools], cioè il pacchetto degli strumenti pronti che userai nel capitolo 12. Il doppio uguale==fissa la versione.
Crea poi, sempre nella stessa cartella, un file chiamato esattamente .env (con il punto davanti e nient'altro) con queste due righe. Per ora copialo così: nel capitolo 7 sceglierai il tuo modello. Lo script di prova non contatta nessun modello, quindi non serve altro.
MODEL=ollama/qwen2.5:7b
CREWAI_DISABLE_TELEMETRY=trueInfine, dal terminale posizionato in corso-crewai, lancia lo script. --env-file .env dice a uv di leggere le impostazioni dal file .env prima di avviare lo script. Su macOS e Linux:
uv run --env-file .env prova_crewai.pySu Windows il comando è identico:
uv run --env-file .env prova_crewai.pyLa prima volta uv deve scaricare CrewAI e tutte le sue dipendenze: 144 pacchetti. Sul computer di prova, con una connessione veloce, ha impiegato una quarantina di secondi; con una connessione più lenta può volerci qualche minuto. La seconda volta ritrova tutto già pronto e parte subito. Ecco l'output reale delle due esecuzioni una dopo l'altra:
Se l'ultima riga è crewai 1.15.21 | MODEL da .env: ollama/qwen2.5:7b, il tuo computer è pronto: uv ha installato CrewAI in un ambiente riservato allo script e ha letto il file .env. Non hai toccato il Python del sistema e non hai creato nessun progetto.
Se lo script scrive MODEL da .env: None, uv non ha trovato il file delle impostazioni: controlla di aver scritto --env-file .env nel comando, che il file si chiami proprio .env (non .env.txt né env) e che il terminale sia nella cartella giusta.
Prova tu: fai stampare allo script anche la versione di Python
Aggiungi in fondo a prova_crewai.py le due righe seguenti e rilancia lo script con lo stesso comando.
import sysrende disponibili le informazioni sul Python in uso.print("Python", sys.version.split()[0])stampa il numero di versione.
Questa volta uv non scarica nulla, perché le dipendenze non sono cambiate, e vedrai una riga in più con un numero tra 3.10 e 3.13: è la versione scelta da uv rispettando requires-python. Se provi a togliere --env-file .env dal comando, la prima riga mostrerà MODEL da .env: None.
- Si installa prima uv (con
curlsu macOS e Linux, con PowerShell su Windows), poi la CLI conuv tool install crewai. - Se compare l'avviso sul PATH:
uv tool update-shelle riapri il terminale. Verifica concrewai version. - Su Windows l'errore su
float.hsi risolve con i Visual Studio Build Tools; Python deve essere tra 3.10 e 3.13. uv tool install crewai --upgradeaggiorna solo la CLI; la telemetria si spegne conCREWAI_DISABLE_TELEMETRY=true.- Gli esempi del corso sono script con l'intestazione
# /// script, lanciati conuv run --env-file .env nome.py.
Il computer sa eseguire CrewAI, ma agli agenti manca ancora il cervello: nel prossimo capitolo scegli il modello, online o sul tuo computer, e scrivi il file .env per davvero.
Corso indipendente, non affiliato a CrewAI Inc. Contenuti verificati su CrewAI 1.15.21 il 15 settembre 2026.