Chi si avvicina a Python presto si imbatte in un problema comune: come gestire librerie diverse per progetti diversi senza creare confusione? La risposta è: usare gli ambienti virtuali all’interno dei propri progetti.
In questo articolo spiegheremo come creare un progetto con lo strumento uv, come associare un ambiente virtuale a un progetto e vedremo un esempio pratico con la libreria arXiv [3], che permette di cercare articoli scientifici dal famoso archivio online. Vedremo queste operazioni su Windows, ma su Ubuntu o su MacOs o su una qualsiasi distribuzione Linux le operazioni da fare sono simili. Utilizzeremo un programma di esempio, python-project-arxiv, che ho messo a disposizione su GitHub [5].
Cos’è un ambiente virtuale?
Un ambiente virtuale è una copia isolata di Python che contiene i propri pacchetti che sono separati da quelli installati a livello globale sul sistema.
I vantaggi principali sono:
- evitare conflitti tra versioni di Python e di librerie richieste da progetti diversi;
- mantenere ordinato e riproducibile l’ambiente di lavoro;
- poter condividere facilmente le dipendenze di un progetto con altri.
In pratica, per ogni progetto, si può avere un ambiente isolato in cui c’è installata una versione ben precisa di Python, con solo e soltanto le librerie che servono per quel progetto e nella versione richiesta in quel progetto.
Quando un ambiente virtuale è attivo, ogni comando python e pip si riferisce solo a quell’ambiente, non al Python di sistema, quindi le librerie installate riguardano solo l’ambiente virtuale.
Perché usare uv?
Lo strumento uv ( che è un gestore di pacchetti e progetti) rende il processo di creazione di ambienti virtuali più veloce e intuitivo.
Con uv si possono:
- creare e gestire ambienti virtuali;
- installare pacchetti con un’alternativa rapida a
pip; - eseguire script direttamente dentro un ambiente, anche senza attivarlo manualmente.
Alternative a uv possono essere: usare venv (ambienti virtuali) + pip (installazione pacchetti) oppure utilizzare Anaconda [2] che è una suite che svolge entrambe le funzionalità ma è più complessa ed è indicata soprattutto per applicazioni di data science e machine learning.
Installazione di uv
Per installare uv basta lanciare uno dei seguenti comandi:
- Su Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh - Su Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Dopo l’installazione, il comando uv sarà disponibile nel terminale e quindi il comando con il comando uv --version è possibile verificare qual è la versione installata.
Creare un progetto con uv
Ora creiamo un progetto con il suo ambiente virtuale. In questa fase possiamo anche specificare quale versione di Python usare, per esempio la 3.11:
- A linea di comando, per esempio nella PowerShell di Windows, digitiamo il seguente comando che creerà la struttura base del progetto cioè un insieme di file e cartelle:
uv init python-project-arxiv --python '>=3.11'
- Creiamo l’ambiente virtuale associato al progetto con questo comando (verrà creata la cartella .venv) :
uv sync
- Aggiungiamo le librerie che ci servono nel progetto, in questo caso arxiv (verrà aggiornato il file pyproject.toml):
uv add arxiv
- Possiamo già provare che tutto funzioni esegendo il comando:
uv run main.py
- A questo punto possiamo scrivere il codice che ci serve nel file main.py che poi rinominiamo in search_articles.py per comodità.
- Una volta scritto il programma possiamo lanciare il seguente comando per eseguirlo:
uv run search_articles.py
Nello screenshot seguente si vede come il Python usato nel primo comando sia quello di sistema, mentre quello nel secondo comando sia quello interno all’ambiente virtuale:
Come utilizzare un progetto realizzato con uv
Ora supponiamo di aver salvato il progetto su un repository GIT e di voler: scaricare il progetto, ricreare l’ambiente virtuale ed eseguire il programma al suo interno.
I comandi da utilizzare sono i seguenti:
git clone https://github.com/ilclaudio/python-project-arxiv.git cd .\python-project-arxiv\ uv sync uv run .\search_articles.py
Da notare che, sul PC utilizzato, è necessario che siano installati Python e uv, ma che Python può avere una versione diversa da quella del progetto. Il Python richiesto dal progetto verrà installato all’interno dell’ambiente virtuale.
Cos’è la libreria arXiv?
arXiv [4] è una libreria Python che permette di interrogare arXiv.org [3], un archivio online di articoli scientifici molto usato in matematica, fisica, informatica e altre discipline. Con arXiv si possono cercare articoli per argomento, filtrare i risultati e scaricare metadati come titolo, autori e link.
Esempio pratico: cercare articoli con arXiv
Se non ci serve creare un progetto, possiamo crere un ambiente virtuale temporaneo con questi comandi:
mkdir arxiv-example cd arxiv-example uv venv --python 3.11 uv pip install arxiv .venv\Scripts\Activate.ps1
L’ultimo comando attiva l’ambiente virtuale su PowerShell, su Linux il comando è source .venv/bin/activate, su shell Windows il comando è: .venv\Scripts\activate.bat.
Con l’ambiente virtuale attivo e la libreria arXiv installata, apriamo una shell Python e proviamo a cercare, per esempio, tre articoli scientifici che parlino di sistemi RAG, ordinati per rilevanza.
Quindi apriamo il prompt con il comando:
python
E poi copiamo e incolliamo questo codice:
import arxiv
client = arxiv.Client()
search = arxiv.Search(
query="RAG systems",
max_results=3,
sort_by=arxiv.SortCriterion.Relevance
)
for result in client.results(search):
print(result.title, "-", result.entry_id)
Dopo aver premuto Invio, otterremo una lista di articoli recenti pertinenti al tema “RAG systems” con i link alle loro pagine su arXiv.
Con il comando deactivate è possibile uscire dall’ambiente virtuale.
Eseguire la ricerca da script
Ovviamente con il prompt di Python si possono fare delle prove, ma poi sarà necessario scrivere degli script.
Per esempio, possiamo scrivere in un file papers.py il seguente codice:
import arxiv
client = arxiv.Client()
search = arxiv.Search(
query="RAG systems",
max_results=3,
sort_by=arxiv.SortCriterion.Relevance
)
for result in client.results(search):
print(result.title, "-", result.entry_id)
E poi eseguirlo da PowerShell:
python papers.py
Oppure, anche senza attivare l’ambiente:
uv run python papers.py
Salvataggio e riuso dell’ambiente
Una volta installate le librerie, posso salvare l’elenco, sempre all’interno dell’ambiente virtuale, con questo comando:
uv pip freeze > requirements.txt
Allo stesso modo, avendo già una cartella di progetto con un file requirements.txt, posso installare tutte le librerie in un ambiente virtuale con questi due comandi:
cd mio-progetto uv venv uv pip install -r requirements.txt
Il file requirements.txt serve per congelare e riprodurre esattamente lo stesso ambiente Python del progetto perché contiene sia le dipendenze dirette (quelle installate esplicitamente) sia quelle indirette (le librerie richieste dai pacchetti installati).
Conclusione
Gli ambienti virtuali sono uno strumento fondamentale per lavorare con Python in modo ordinato e professionale. Con uv, la loro gestione diventa semplice e veloce. La libreria arXiv è solo un esempio di come un ambiente virtuale ti permetta di sperimentare con librerie diverse senza rischiare conflitti o “incasinare” il tuo sistema globale. I due modi di utilizzare uv visti in questo post sono alternativi, diciamo che il primo è una evoluzione del secondo e permette di gestire i progetti in modo più ordinato.
Fonti e riferimenti
- Installing and managing Python with UV sito ufficiale di Astral.
- Anaconda: sito ufficiale.
- Archivio arXiv: articoli scientifici online, Cornell University.
- Libreria Python arxiv.
- Programma d’esempio: python-project-arxiv, GitHub.