Gestire più versioni di Python con pyenv

Introduzione

Quando si inizia a lavorare con Python, spesso è sufficiente installare una sola versione del linguaggio. Con il tempo, però, può capitare di dover mantenere applicazioni diverse: un progetto datato potrebbe richiedere Python 3.10, mentre uno più recente potrebbe essere compatibile soltanto con Python 3.12. Installare e selezionare manualmente versioni differenti può diventare scomodo e aumentare il rischio di errori.

In questo tutorial vedremo come utilizzare pyenv, uno strumento che consente di installare più versioni di Python e scegliere quale usare a livello globale, di cartella o di singolo progetto. L’obiettivo è creare un piccolo script che mostri la versione attiva e verifichi che l’ambiente di esecuzione sia quello desiderato.

È importante distinguere pyenv da un ambiente virtuale. pyenv gestisce le versioni dell’interprete Python, mentre un ambiente virtuale, come quello creato con venv, separa i pacchetti installati per ciascun progetto. I due strumenti possono essere usati insieme.

Codice completo

Creiamo un file chiamato verifica_ambiente.py. Lo script usa soltanto la libreria standard, quindi non richiede pacchetti esterni.

import platform
import sys


def mostra_ambiente():
    """Visualizza informazioni sull´interprete Python in uso."""
    print("Informazioni sull´ambiente Python")
    print("-" * 36)
    print(f"Versione Python: {platform.python_version()}")
    print(f"Esecutabile: {sys.executable}")
    print(f"Sistema operativo: {platform.system()}")
    print(f"Architettura: {platform.machine()}")

    versione = sys.version_info

    if versione.major == 3 and versione.minor >= 11:
        print("Risultato: versione compatibile.")
    else:
        print("Risultato: è consigliata Python 3.11 o superiore.")


if __name__ == "__main__":
    mostra_ambiente()

Per eseguire lo script, dopo aver selezionato la versione desiderata, utilizzeremo il comando:

python verifica_ambiente.py

Su alcuni sistemi il comando corretto potrebbe essere python3.

Spiegazione

Installare pyenv

Su Linux e macOS, pyenv viene normalmente installato tramite lo script ufficiale del progetto. Dopo l’installazione è necessario riaprire il terminale oppure ricaricare la configurazione della shell.

curl https://pyenv.run | bash

Il comando scarica e configura pyenv nella directory dell’utente. Il programma di installazione indica generalmente quali righe aggiungere al file di configurazione della shell, ad esempio ~/.bashrc o ~/.zshrc.

Su Windows è possibile utilizzare pyenv-win, un progetto compatibile con l’ambiente Windows. Dopo l’installazione, apriamo PowerShell e verifichiamo che il comando sia disponibile:

pyenv --version

Se il comando non viene riconosciuto, è probabile che la directory di pyenv non sia stata aggiunta alla variabile d’ambiente PATH. In questo caso occorre controllare la configurazione del sistema e riavviare il terminale.

Installare una versione specifica

Per visualizzare le versioni disponibili possiamo usare:

pyenv install --list

Successivamente installiamo, ad esempio, Python 3.11.9:

pyenv install 3.11.9

La compilazione può richiedere alcuni minuti, soprattutto su sistemi meno recenti. Se l’operazione fallisce su Linux, potrebbero mancare librerie di sviluppo necessarie alla compilazione dell’interprete.

Scegliere la versione attiva

Per impostare Python 3.11.9 come versione predefinita per l’utente corrente:

pyenv global 3.11.9
python --version

È anche possibile impostare una versione soltanto per una determinata directory. Entriamo nella cartella del progetto e lanciamo:

mkdir progetto-demo
cd progetto-demo
pyenv local 3.11.9

Il comando crea un file chiamato .python-version. Quando il terminale si trova nella cartella del progetto, pyenv seleziona automaticamente la versione indicata nel file. Uscendo dalla directory, torna in vigore la configurazione globale.

Controllare quale Python viene eseguito

Non è sufficiente controllare soltanto il numero di versione: è utile sapere anche quale eseguibile viene utilizzato. Il comando seguente mostra il percorso risolto dalla shell:

pyenv which python

In alternativa, lo script completo mostrato in precedenza visualizza il valore di sys.executable. Questa informazione è particolarmente utile quando un editor, un terminale e un ambiente virtuale sembrano utilizzare interpreti differenti.

Best practice

Definisci la versione del progetto: usa pyenv local nella directory del progetto, così tutti i collaboratori conoscono l’interprete previsto.
Controlla sempre l’eseguibile: confronta python --version con pyenv which python prima di installare pacchetti.
Non modificare manualmente i file installati: usa i comandi di pyenv per installare, selezionare o rimuovere le versioni.
Documenta i requisiti: puoi indicare la versione Python nel README del progetto o in un file dedicato come .python-version.
Abbina pyenv a venv: dopo aver scelto l’interprete, crea un ambiente virtuale per isolare le dipendenze.
Evita versioni obsolete: per nuovi progetti scegli una versione supportata e aggiornata, verificando il ciclo di vita ufficiale di Python.

Un possibile flusso di lavoro è il seguente:

cd progetto-demo
pyenv local 3.11.9
python -m venv .venv
source .venv/bin/activate
python verifica_ambiente.py

Su Windows PowerShell, l’attivazione dell’ambiente virtuale usa generalmente:

.venvScriptsActivate.ps1

Riepilogo

pyenv è uno strumento pratico per gestire più interpreti Python sullo stesso computer. Dopo l’installazione è possibile elencare le versioni disponibili, installare quella necessaria e selezionarla globalmente oppure soltanto all’interno di un progetto. Il file .python-version rende la configurazione chiara e riproducibile.

Lo script di verifica consente di controllare versione, percorso dell’interprete e sistema operativo. Questa semplice verifica evita molti problemi, soprattutto quando sono presenti più installazioni di Python. Per un progetto completo, la soluzione consigliata è combinare pyenv per la versione del linguaggio e venv per l’isolamento dei pacchetti.

Approfondisci con risorse ufficiali

Add as preferred source on Google