Python su server: venv, pipx o uv?
Su Ubuntu 24.04 pip install restituisce "externally-managed-environment": ecco quando scegliere venv, pipx o uv e come collegarlo a systemd.
Perché pip install non funziona su un server Ubuntu appena installato
La scelta tra un Python venv, pipx e uv su un server dipende da una sola domanda: che cosa stai installando? Le dipendenze di un'applicazione devono trovarsi in un ambiente virtuale all'interno della directory dell'applicazione. Gli strumenti a riga di comando che vuoi eseguire digitandone il nome devono essere installati con pipx. uv svolge entrambe le funzioni e aggiunge un lockfile, che diventa importante non appena una seconda macchina deve creare lo stesso ambiente. Nessuno di questi strumenti installa pacchetti nel Python di sistema, perché un server Ubuntu aggiornato lo impedisce esplicitamente.
Esegui sudo pip install requests su Ubuntu 24.04: pip si interrompe prima di scaricare anche un solo file.
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip.
If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.Questo è PEP 668 (Python enhancement proposal 668, "ambienti gestiti esternamente") in azione. Debian e Ubuntu inseriscono un file marker accanto all'interprete, in /usr/lib/python3.12/EXTERNALLY-MANAGED, e pip rifiuta di scrivere in qualsiasi interprete che lo contenga.
La regola esiste a causa dell'ordine di sys.path. apt installa le librerie in /usr/lib/python3/dist-packages. pip, eseguito come root sull'interprete di sistema, scrive in /usr/local/lib/python3.12/dist-packages e il sistema di pacchettizzazione Debian inserisce quella directory prima nel percorso di ricerca. Visualizza l'ordine con python3 -c 'import sys; print(sys.path)' e leggilo. In questo modo, la copia scritta da pip nasconde la copia installata da apt per ogni programma del server eseguito con /usr/bin/python3, inclusi gli strumenti della distribuzione. cloud-init importa requests, jinja2 e PyYAML da quell'interprete. Se aggiorni uno di questi pacchetti con pip e installi una release incompatibile, al riavvio successivo può smettere di funzionare qualcosa che non hai mai modificato, mostrando un traceback con il nome di un pacchetto che non sapevi facesse parte della catena delle dipendenze. apt continua a registrare la propria versione come installata, quindi non ricevi alcun avviso. La correzione consiste nel rimuovere la copia di pip con sudo pip uninstall --break-system-packages requests, perché sudo apt reinstall python3-requests da solo riscrive soltanto la copia di apt che era già nascosta.
La regola da seguire è semplice. Il Python di sistema appartiene alla distribuzione. Non installarvi pacchetti, non aggiornarne le librerie con pip e non eliminare il file EXTERNALLY-MANAGED per nascondere il messaggio. L'unico compito da assegnare a /usr/bin/python3 è la creazione di ambienti virtuali.
venv, pipx o uv: criterio per la scelta
Scegli in base a ciò che devi installare, non in base allo strumento di cui hai letto più recentemente.
- Un'applicazione che distribuisci ed esegui come servizio, ad esempio un progetto Django o Flask: un ambiente virtuale (venv) nella directory dell'applicazione.
- Uno strumento da riga di comando che vuoi su
PATH, ad esempioansibleohttpie: pipx, che assegna a ogni strumento un ambiente privato e crea un unico collegamento inPATH. - Un progetto che richiede un file di lock, installazioni più rapide o una versione di Python che la distribuzione non fornisce: uv, che crea un normale venv oltre a un file
uv.lock. - Una libreria richiesta da uno strumento della distribuzione e non dal tuo codice:
sudo apt install python3-<name>, l'unico metodo supportato per aggiungere elementi all'interprete di sistema.
pipx e uv tool install svolgono lo stesso compito, quindi un server che dispone già di uv non ha bisogno anche di pipx. Il framework web scelto non cambia nulla in questo caso: Django e Flask su un VPS differiscono per ciò che viene installato in requirements.txt, non per il modo in cui viene creato l'ambiente circostante. Tutti gli esempi seguenti usano Ubuntu 24.04 e Python 3.12 incluso nella distribuzione; se la tua versione è diversa, modifica la versione nei percorsi.
Creare il venv per l'applicazione
Ubuntu separa il modulo venv dal pacchetto Python di base. Su un'immagine minimale, quindi, il primo tentativo fallisce con un messaggio che indica esattamente ciò che manca.
The virtual environment was not created successfully because ensurepip is not
available. On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.
apt install python3.12-venvInstallalo, quindi crea l'ambiente con l'utente che sarà proprietario del codice.
sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txtNota cosa non è presente: niente source e niente activate. /srv/myapp/.venv/bin/pip viene installato in quell'ambiente in base al percorso del binario, non per effetto di variabili esportate nella shell. Verificalo prima di procedere.
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'Il comando stampa /srv/myapp/.venv. Se stampa /usr, stai usando l'interprete di sistema e i pacchetti sono stati installati in un percorso diverso da quello previsto.
Due proprietà di un venv determinano le operazioni che puoi eseguire in seguito. Un venv non è rilocabile, perché ogni script entry point in bin/ contiene una riga shebang assoluta: head -1 /srv/myapp/.venv/bin/pip legge #!/srv/myapp/.venv/bin/python. Se rinomini la directory padre, questi script falliscono con bad interpreter: No such file or directory. Un venv mantiene inoltre l'interprete che lo ha creato. Questo valore è registrato nella riga home di /srv/myapp/.venv/pyvenv.cfg, mentre bin/python3 è un symlink a /usr/bin/python3. Se aggiorni la release e quel percorso punta ora a una versione più recente di Python, il nuovo interprete cerca i pacchetti in una directory lib/python3.13 che il venv non contiene. Di conseguenza, il servizio non si avvia e restituisce ModuleNotFoundError. In entrambi i casi la soluzione è la stessa: elimina il venv e creane uno nuovo da requirements.txt. La ricreazione richiede pochi secondi. Non copiare mai un venv tra macchine.
Dove si trova il venv e chi ne è il proprietario
Posizionalo accanto al codice in /srv/myapp/.venv e mantieni un solo venv per applicazione. In questo modo il deployment consiste in un'unica directory, l'unità systemd utilizza un percorso invariabile e due applicazioni non possono mai interferire tra loro a causa dell'aggiornamento condiviso di una dipendenza. Non posizionare un venv in una directory che il server Web pubblica direttamente, perché contiene le dipendenze e spesso anche la configurazione.
La proprietà richiede una verifica di pochi secondi. Assegna a un utente deploy la proprietà del codice e dell'ambiente, quindi concedi all'account di servizio soltanto i permessi di lettura ed esecuzione.
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappIl servizio può ora importare le proprie dipendenze, ma non può sovrascriverle. Di conseguenza, una vulnerabilità di esecuzione del codice nell'applicazione Web non può sostituire di nascosto una libreria sul disco e mantenerla dopo un riavvio. Lo stesso principio, applicato al resto della macchina, è descritto in eseguire i servizi con utenti dotati del minimo privilegio.
pipx per gli strumenti da riga di comando
pipx installa applicazioni, non librerie. Ogni strumento riceve un proprio ambiente in ~/.local/share/pipx/venvs/<name> e gli eseguibili dello strumento vengono collegati in ~/.local/bin. In questo modo, due strumenti che richiedono versioni diverse della stessa libreria non entrano in conflitto.
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx ensurepath aggiunge ~/.local/bin a PATH modificando il file di avvio della shell. Non può modificare la shell già aperta. Per questo, se subito dopo l'installazione http: command not found restituisce un errore, in genere non è stato ancora eseguito il logout e il nuovo login. Il ~/.profile predefinito di Ubuntu aggiunge ~/.local/bin soltanto se la directory esiste già al momento del login. Per questo il problema si presenta una sola volta con un nuovo account e non si ripete.
Se si indica a pipx una libreria, l'operazione viene rifiutata con un messaggio che inizia con:
No apps associated with package requests.Il messaggio indica che pipx è lo strumento sbagliato per quell'operazione. Le librerie devono essere installate nel venv di un'applicazione.
Su un server, il percorso di installazione è l'aspetto più importante. Un semplice pipx install installa tutto nella home directory di un singolo utente. Un'unità systemd eseguita come myapp non può accedervi. Anche un cron job eseguito da root non può accedervi. Inoltre sudo non lo troverà, perché secure_path in /etc/sudoers sostituisce PATH con un elenco fisso. Se uno strumento deve essere disponibile per l'intero sistema, installalo globalmente.
sudo pipx install --global ansible
sudo pipx ensurepath --globalL'opzione --global colloca gli ambienti in /opt/pipx e collega gli eseguibili in /usr/local/bin. Questa directory è inclusa nel PATH predefinito e in secure_path. Controlla prima la versione con pipx --version. Ubuntu 24.04 include pipx 1.4.3, che è precedente a --global. Una versione precedente di pipx risponde con unrecognized arguments: --global. Con quella versione, imposta manualmente le due directory documentate:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansiblecommand -v ansible dovrebbe stampare /usr/local/bin/ansible. Se stampa un percorso sotto /home, lo strumento è stato installato nell'account di un singolo utente e nessun servizio potrà trovarlo.
uv quando serve un lockfile
uv è un singolo binario di Astral che riunisce le funzionalità di pip, venv e pip-tools e può anche scaricare gli interpreti. È abbastanza veloce da rendere evidente la differenza su un VPS di piccole dimensioni e scrive un lockfile effettivo.
L'installer ufficiale installa uv e uvx in ~/.local/bin:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionEseguire tramite pipe uno script in una shell su un server richiede una breve verifica. Blocca la versione nell'URL e leggi il file prima di eseguirlo:
curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.shAnche pipx install uv funziona, se pipx è già presente. uv è un singolo binario autonomo, senza dipendenze Python proprie, quindi copiarlo in /usr/local/bin è un modo valido per condividerlo con tutti gli utenti del sistema.
Per un progetto con un pyproject.toml, il flusso di lavoro richiede quattro comandi e solo l'ultimo viene eseguito sul server.
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devuv lock scrive uv.lock, un lockfile multipiattaforma che contiene le versioni risolte esatte, da salvare nel repository accanto al codice. uv sync crea .venv nella directory principale del progetto per rispettarlo. Sul server, --frozen è il flag importante: la documentazione lo definisce come l'uso delle versioni nel lockfile come fonte autorevole, senza verificare se il lockfile è aggiornato. È il comportamento richiesto da un deployment. --no-dev esclude il gruppo delle dipendenze di sviluppo.
Un progetto requirements.txt esistente non richiede conversioni, perché uv usa la sintassi di pip:
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtIl risultato è un normale ambiente virtuale, con una differenza: uv non installa pip al suo interno. Di conseguenza, .venv/bin/pip e .venv/bin/python -m pip non funzionano se l'ambiente non viene creato con uv venv --seed. Usa invece uv pip per installare. Nel resto di questa guida non viene eseguito pip nell'ambiente, quindi non cambia altro.
Prima di usare uv su un server è utile conoscere una sua impostazione predefinita. L'impostazione python-preference ha come valore predefinito managed. La documentazione specifica che seleziona gli interpreti "scaricati e installati da uv" invece di quelli già presenti nel sistema. Quindi uv venv --python 3.13 su un sistema che contiene soltanto la versione 3.12 scarica silenziosamente la versione 3.13 in ~/.local/share/uv/python invece di terminare con un errore. Su un laptop questo è comodo, ma su un server può creare sorprese, perché il servizio dipende da un interprete nella directory home e apt upgrade non lo aggiornerà mai. Imposta python-preference su only-system in uv.toml se vuoi usare l'interprete della distribuzione. Se vuoi collocare l'ambiente in una directory diversa dalla directory principale del progetto, UV_PROJECT_ENVIRONMENT specifica la directory da usare per l'ambiente virtuale del progetto.
Indicare a systemd l’interprete del venv, non activate
È qui che la maggior parte delle distribuzioni Python si interrompe, perché si fraintende cosa fa activate.
bin/activate è uno script shell. Antepone la directory bin del venv a PATH, imposta VIRTUAL_ENV, salva i valori precedenti affinché deactivate possa ripristinarli e modifica il prompt. Non contiene nulla che l’interprete legga direttamente. L’attivazione è una comodità per chi digita python in una shell.
A selezionare effettivamente l’ambiente è il file dell’interprete eseguito. Quando viene avviato /srv/myapp/.venv/bin/python, il modulo Python site cerca un file pyvenv.cfg nella directory che contiene l’eseguibile e nella directory padre. Se trova /srv/myapp/.venv/pyvenv.cfg, imposta sys.prefix sul venv e inserisce quindi la directory site-packages di quel venv in sys.path. Questo è l’intero meccanismo. Non richiede variabili d’ambiente né una shell.
Per questo questa unità non viene mai avviata:
[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:appmyapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXECExecStart non è una riga di comando della shell. systemd esegue direttamente un programma, quindi non esiste alcun builtin source, && viene passato come argomento letterale e non viene eseguita alcuna espansione della shell, oltre alle poche documentate da systemd.
Questa unità invece si avvia e poi termina:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 è l’interprete di sistema e il suo sys.path non ha mai contenuto il tuo venv. Lo stesso comando funziona nella sessione SSH solo perché avevi attivato il venv in quella sessione: la shell aveva quindi risolto python3 tramite PATH, indirizzandolo invece a .venv/bin/python3.
Racchiudere il comando in /bin/bash -c 'source ... && gunicorn ...' funziona. Tuttavia inserisce una shell tra systemd e il processo senza alcun vantaggio, quando è sufficiente un percorso assoluto:
[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pagersystemctl status myapp dovrebbe restituire active (running) con un Main PID corrispondente al processo gunicorn. In caso contrario, consulta il journal.
La riga Environment=PATH= non serve a ExecStart, che contiene già un percorso completo. Serve ai processi avviati dalla tua applicazione. Un servizio eredita da systemd un PATH predefinito e ridotto. Di conseguenza, il codice Python che chiama subprocess.run(["ffmpeg", ...]), oppure un comando di gestione che avvia uno script console dal venv, non trova ciò che gli serve. Anteporre la directory bin del venv al activate è l’unica parte di activate che il servizio utilizza realmente. Controlla cosa ha ricevuto effettivamente l’unità con systemctl show -p Environment myapp.
La stessa regola vale per le attività pianificate. Su Ubuntu, cron non passa a un job il PATH della tua shell o del demone. Se il crontab non imposta PATH, ogni job riceve il valore predefinito compilato in /usr/bin:/bin e /etc/environment non lo sovrascrive. Quel valore non contiene mai il tuo venv. Di conseguenza, una riga del crontab che contiene python3 /srv/myapp/cleanup.py esegue l’interprete di sistema e alle tre del mattino termina con ModuleNotFoundError. cron invia l’errore al proprietario del crontab oppure all’indirizzo MAILTO, se ne hai impostato uno. Sulla maggior parte dei server questo corrisponde a una casella locale che nessuno legge. Se non è installato alcun programma di posta, cron scarta l’output e scrive soltanto No MTA installed, discarding output nel log di sistema. Inserisci anche lì il percorso assoluto del venv. Per inviare quell’output al journal e conservare invece una registrazione dell’ultima esecuzione, una coppia di servizio e timer systemd utilizza la stessa riga ExecStart.
Docker sostituisce questa decisione?
Un container ha un filesystem proprio, quindi la questione cambia forma invece di scomparire. In un'immagine ufficiale come python:3.12-slim, Python è integrato in /usr/local e non contiene alcun indicatore EXTERNALLY-MANAGED. Per questo, pip install come root è il metodo previsto per aggiungere pacchetti e un venv offre pochi vantaggi. Eseguite invece il build di FROM ubuntu:24.04 e incontrerete di nuovo externally-managed-environment all'interno dell'immagine, per lo stesso motivo che vale sull'host: è l'interprete della distribuzione che contiene il file indicatore della distribuzione.
Molte immagini usano comunque un venv, perché semplifica una build a più stage. Lo stage builder installa i pacchetti in /opt/venv e lo stage runtime copia quella directory, lasciando indietro i compilatori. Anche il problema dell'attivazione viene trasferito. Una riga RUN source /opt/venv/bin/activate modifica soltanto la shell del layer di build, quindi, all'avvio, il container usa l'interprete di sistema e genera ModuleNotFoundError. Impostate ENV PATH="/opt/venv/bin:$PATH" oppure fornite a CMD il percorso assoluto /opt/venv/bin/gunicorn. È lo stesso errore visto con systemd, ma in un file diverso.
Un container sostituisce quindi la questione dell'interprete, perché l'immagine fissa l'interprete e tutto ciò che dipende da esso. Non sostituisce però la questione del pinning. Un'immagine compilata da un requirements.txt senza versioni fissate risolve versioni diverse il mese prossimo. Il tag dell'immagine è quindi riproducibile, ma la build che l'ha prodotto non lo è. Un lockfile come uv.lock, oppure un file requirements con tutte le versioni fissate, elimina questa differenza, dentro o fuori da un container. Quando una sola applicazione viene eseguita su un VPS tramite systemd, un container trasferisce soprattutto questa stessa decisione in un Dockerfile, perché systemd riavvia già un processo che termina con errore e ne acquisisce l'output nel journal. Eseguire Docker su un VPS è utile quando volete che sia l'immagine compilata stessa l'elemento da distribuire.
FAQ
Posso usare semplicemente pip install con --break-system-packages?
Non su un server che deve restare operativo. Il flag fa esattamente ciò che indica: rimuove la protezione e pip scrive in /usr/local/lib/python3.12/dist-packages, che precede la directory apt in sys.path. La versione installata sovrascrive quindi quella della distribuzione per ogni script di sistema eseguito con /usr/bin/python3, mentre apt continua a considerare installata la propria versione. Il conflitto non viene rilevato finché qualcosa non si rompe. In un'immagine container che ricrei da zero ogni volta, il danno resta confinato a quell'immagine, quindi questa scelta può essere giustificata. Su una macchina che amministri, crea un venv. È sufficiente un comando.
Dove deve risiedere l'ambiente virtuale su un server?
Nella directory dell'applicazione, come /srv/myapp/.venv, con il proprietario impostato sull'utente deploy e l'account del servizio autorizzato soltanto alla lettura e all'esecuzione. Usa un venv per ogni applicazione, perché un ambiente condiviso consente a un aggiornamento per la prima applicazione di compromettere la seconda. Non spostare né copiare un venv dopo averlo creato: ogni script entry-point nella directory bin/ contiene quel percorso assoluto nella riga shebang, quindi un venv spostato non funziona e restituisce bad interpreter: No such file or directory. Eliminalo e ricrealo da requirements.txt.
Perché il mio servizio systemd termina con ModuleNotFoundError?
Perché l'unità esegue un interprete diverso da quello del venv. Esegui systemctl cat myapp e leggi ExecStart. Deve indicare /srv/myapp/.venv/bin/python oppure, tramite un percorso assoluto, uno script console della stessa directory bin/. Eseguire direttamente activate in ExecStart non può funzionare, perché ExecStart non è una shell e systemd segnala Failed to locate executable source con status=203/EXEC. Aggiungi Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin, così anche i sottoprocessi avviati dal codice troveranno gli strumenti del venv.
Devo usare uv invece di venv e pip?
Usa uv quando vuoi un lockfile, quando i tempi di installazione sono abbastanza lunghi da costituire un problema oppure quando ti serve una versione di Python non distribuita dalla tua distribuzione. Crea un venv ordinario, quindi l'unità systemd e la struttura dei file non cambiano, e uv sync --frozen installa esattamente ciò che registra il lockfile. Se una singola applicazione viene distribuita da git con un requirements.txt fissato e l'installazione termina in pochi secondi, python3 -m venv è già sufficiente e sul server dovrai mantenere aggiornato un binario in meno.