venv, pipx ou uv sur Ubuntu : quel outil choisir ?
L'erreur externally-managed-environment bloque pip sur Ubuntu 24.04. Apprenez à choisir entre venv, pipx et uv selon vos besoins et configurez correctement vos services systemd.
Pourquoi pip install échoue sur un serveur Ubuntu vierge
Choisir entre un venv Python, pipx et uv sur un serveur revient à répondre à une seule question : qu’installez-vous ? Les dépendances d’une application doivent être installées dans un environnement virtuel situé dans le répertoire de l’application. Les outils en ligne de commande que vous voulez appeler par leur nom doivent être installés avec pipx. uv couvre ces deux usages et ajoute un lockfile, ce qui devient utile dès qu’une deuxième machine doit construire le même environnement. Aucun de ces outils n’installe toutefois de paquets dans le Python système, car un serveur Ubuntu récent le refuse explicitement.
Exécutez sudo pip install requests sur Ubuntu 24.04 : pip s’arrête avant de télécharger le moindre fichier.
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.C’est PEP 668 (Python enhancement proposal 668, « environnements gérés de l’extérieur ») qui fonctionne comme prévu. Debian et Ubuntu placent un fichier marqueur à côté de l’interpréteur, dans /usr/lib/python3.12/EXTERNALLY-MANAGED, et pip refuse d’écrire dans tout interpréteur qui en contient un.
Cette règle existe à cause de l’ordre de sys.path. apt installe les bibliothèques dans /usr/lib/python3/dist-packages. Exécuté en tant que root avec l’interpréteur système, pip écrit dans /usr/local/lib/python3.12/dist-packages, et le système de paquets Debian place ce répertoire plus tôt dans le chemin de recherche. Affichez vous-même cet ordre avec python3 -c 'import sys; print(sys.path)'. La copie écrite par pip masque donc la copie installée par apt, pour tous les programmes de la machine qui s’exécutent avec /usr/bin/python3, y compris les outils de la distribution. cloud-init importe requests, jinja2 et PyYAML depuis cet interpréteur. Mettez à niveau l’un de ces paquets avec pip, installez une version incompatible, et un service que vous n’avez jamais modifié échouera au démarrage suivant avec une traceback mentionnant un paquet dont vous ignoriez la présence dans la chaîne de dépendances. apt continue d’enregistrer sa propre version comme installée et ne vous avertit donc pas. Pour corriger le problème, supprimez la copie de pip avec sudo pip uninstall --break-system-packages requests, car sudo apt reinstall python3-requests seul ne fait que réécrire la copie d’apt qui était déjà masquée.
La règle à retenir est simple. Le Python système appartient à la distribution. N’y installez rien, ne mettez pas ses bibliothèques à niveau avec pip et ne supprimez pas le fichier EXTERNALLY-MANAGED pour faire disparaître le message. Le seul rôle à confier à /usr/bin/python3 est de créer des environnements virtuels.
venv, pipx et uv : la règle de décision
Choisissez en fonction de ce que vous installez, et non de l'outil dont vous avez entendu parler le plus récemment.
- Une application que vous déployez et exécutez en tant que service, comme un projet Django ou Flask : un environnement virtuel (venv) à l'intérieur du répertoire de cette application.
- Un outil en ligne de commande que vous voulez sur votre
PATH, commeansibleouhttpie: pipx, qui attribue à chaque outil un environnement privé et un lien surPATH. - Un projet qui nécessite un fichier de verrouillage (lockfile), des installations plus rapides ou une version de Python que la distribution ne fournit pas : uv, qui génère un venv classique accompagné d'un fichier
uv.lock. - Une bibliothèque dont un outil de la distribution a besoin, plutôt que votre code :
sudo apt install python3-<name>, la seule méthode supportée pour ajouter quoi que ce soit à l'interpréteur système.
pipx et uv tool install effectuent la même tâche ; une machine qui possède déjà uv n'a donc pas besoin de pipx en plus. Le framework web choisi ne change rien ici : Django et Flask sur un VPS diffèrent par ce qui se trouve dans requirements.txt, mais pas par la manière dont l'environnement est construit. Tout ce qui suit utilise Ubuntu 24.04 et son Python 3.12 ; ajustez donc la version dans les chemins si la vôtre est différente.
Créer le venv de l’application
Ubuntu sépare le module venv du paquet Python de base. Sur une image minimale, la première tentative échoue donc avec un message qui indique précisément ce qui manque.
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-venvInstallez-le, puis créez l’environnement avec l’utilisateur qui possédera le code.
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.txtNotez ce qui n’apparaît pas : ni source, ni activate. /srv/myapp/.venv/bin/pip s’installe dans cet environnement en raison de l’emplacement du binaire, et non à cause d’une variable exportée dans le shell. Vérifiez-le avant de continuer.
/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'Cette commande affiche /srv/myapp/.venv. Si elle affiche /usr, vous utilisez l’interpréteur système et vos paquets ont été installés à un emplacement différent de celui prévu.
Deux propriétés d’un venv déterminent ce que vous pouvez en faire ensuite. Un venv n’est pas déplaçable, car chaque script d’entry point dans bin/ contient une ligne shebang absolue : head -1 /srv/myapp/.venv/bin/pip lit #!/srv/myapp/.venv/bin/python. Si vous renommez le répertoire parent, ces scripts échouent avec bad interpreter: No such file or directory. Un venv conserve également l’interpréteur qui l’a créé, indiqué par la ligne home dans /srv/myapp/.venv/pyvenv.cfg, et bin/python3 est un lien symbolique vers /usr/bin/python3. Mettez à niveau la release afin que ce chemin pointe vers une version plus récente de Python : le nouvel interpréteur recherche alors les paquets dans un répertoire lib/python3.13 que le venv ne contient pas, et le service s’arrête au démarrage avec ModuleNotFoundError. Dans les deux cas, la solution est la même : supprimez le venv et recréez-en un à partir de requirements.txt. La recréation prend quelques secondes. Ne copiez jamais un venv d’une machine à une autre.
Emplacement et droits du venv
Placez-le à côté du code dans /srv/myapp/.venv et conservez un venv par application. Le déploiement constitue alors un répertoire unique, l'unité systemd utilise un chemin fixe, et deux applications ne peuvent jamais se corrompre mutuellement lors d'une mise à jour de dépendance. Ne placez jamais un venv dans un répertoire exposé directement par votre serveur web, car il contient vos dépendances et souvent votre configuration.
La gestion des droits mérite une attention particulière. Laissez un utilisateur deploy posséder le code et l'environnement, et accordez au compte de service uniquement des droits de lecture et d'exécution.
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myappLe service peut désormais importer ses dépendances sans pouvoir les modifier. Ainsi, une faille d'exécution de code dans l'application web ne permet pas de remplacer discrètement une bibliothèque sur le disque pour persister après un redémarrage. Le même raisonnement appliqué au reste de la machine est détaillé dans exécuter des services avec des privilèges restreints.
pipx pour les outils en ligne de commande
pipx installe des applications, pas des bibliothèques. Chaque outil possède son propre environnement sous ~/.local/share/pipx/venvs/<name>, et les exécutables de cet outil sont liés dans ~/.local/bin. Ainsi, deux outils qui nécessitent des versions différentes d’une même bibliothèque n’entrent jamais en conflit.
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx ensurepath ajoute ~/.local/bin à PATH en modifiant le fichier d’initialisation de votre shell. Il ne peut pas modifier le shell que vous utilisez déjà. Si http: command not found s’affiche juste après l’installation, c’est généralement parce que vous ne vous êtes pas encore déconnecté puis reconnecté. Le ~/.profile par défaut d’Ubuntu ajoute ~/.local/bin uniquement si ce répertoire existe déjà lors de la connexion. C’est pourquoi ce problème survient une seule fois pour un nouveau compte.
Si vous indiquez une bibliothèque à pipx, il refuse l’installation avec un message qui commence par :
No apps associated with package requests.Le message indique que pipx n’est pas l’outil adapté. Les bibliothèques doivent être installées dans l’venv d’une application.
Sur un serveur, le point important est l’emplacement. Un simple pipx install place tout dans le répertoire personnel d’un utilisateur. Une unité systemd exécutée avec myapp ne peut pas y accéder. Une tâche cron exécutée par root ne peut pas non plus y accéder. sudo ne le trouvera pas davantage, car secure_path dans /etc/sudoers remplace PATH par une liste fixe. Si toute la machine doit utiliser l’outil, installez-le globalement.
sudo pipx install --global ansible
sudo pipx ensurepath --globalL’option --global place les environnements dans /opt/pipx et lie les exécutables dans /usr/local/bin. Ce répertoire figure dans le PATH par défaut et dans secure_path. Vérifiez d’abord votre version avec pipx --version. Ubuntu 24.04 fournit pipx 1.4.3, qui est antérieur à --global. Une version plus ancienne de pipx répond avec unrecognized arguments: --global. Dans cette version, définissez vous-même les deux répertoires documentés :
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansiblecommand -v ansible doit afficher /usr/local/bin/ansible. S’il affiche un chemin sous /home, l’outil a été installé dans le compte d’un seul utilisateur et aucun service ne le trouvera.
uv pour gérer un fichier de verrouillage
uv est un binaire unique d’Astral qui couvre les fonctions de pip, venv et pip-tools. Il peut également télécharger des interpréteurs.
Il est suffisamment rapide pour que la différence soit visible sur un petit VPS. Il écrit aussi un véritable fichier de verrouillage.
L’installateur officiel place uv et uvx dans ~/.local/bin :
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --versionExécuter un script transmis à un shell sur un serveur demande quelques précautions. Indiquez une version précise dans l’URL et lisez le fichier avant de l’exécuter :
curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.shpipx install uv fonctionne également lorsque pipx est déjà installé. uv est un binaire autonome qui n’a aucune dépendance Python propre. Le copier dans /usr/local/bin est donc une méthode valide pour le partager avec tous les utilisateurs du serveur.
Pour un projet avec un pyproject.toml, le processus comprend quatre commandes. Seule la dernière est exécutée sur le serveur.
uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-devuv lock écrit uv.lock, un fichier de verrouillage multiplateforme contenant les versions résolues exactes. Vous le versionnez à côté de votre code. uv sync construit .venv à la racine du projet pour les faire correspondre. Sur le serveur, --frozen est l’option importante : la documentation la définit comme l’utilisation des versions du fichier de verrouillage comme source de référence, sans vérifier si le fichier est à jour. C’est le comportement attendu pour un déploiement. --no-dev exclut le groupe de dépendances de développement.
Un projet requirements.txt existant ne nécessite aucune conversion, car uv utilise la syntaxe de pip :
uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txtLe résultat est un environnement virtuel ordinaire, avec une différence : uv n’y installe pas pip. .venv/bin/pip et .venv/bin/python -m pip ne fonctionnent donc pas, sauf si vous créez l’environnement avec uv venv --seed. Installez plutôt avec uv pip. Rien dans la suite de ce guide n’exécute pip dans l’environnement. Rien ne change donc par la suite.
Il est utile de connaître une valeur par défaut de uv avant de l’utiliser sur un serveur. Son paramètre python-preference est défini par défaut sur managed. La documentation indique qu’il sélectionne « ceux qui sont téléchargés et installés par uv » plutôt que les interpréteurs déjà présents sur le système. Ainsi, uv venv --python 3.13 sur une machine qui ne fournit que la version 3.12 télécharge discrètement la version 3.13 dans ~/.local/share/uv/python au lieu d’échouer. Ce comportement est pratique sur un ordinateur portable, mais surprenant sur un serveur, car votre service dépend alors d’un interpréteur placé dans un répertoire personnel que apt upgrade ne mettra jamais à jour. Définissez python-preference sur only-system dans uv.toml si vous souhaitez utiliser l’interpréteur de la distribution. Si vous voulez placer l’environnement ailleurs qu’à la racine du projet, UV_PROJECT_ENVIRONMENT indique le répertoire à utiliser pour l’environnement virtuel du projet.
Indiquer à systemd l’interpréteur du venv, pas le script activate
C’est à cet endroit que la plupart des déploiements Python échouent. La cause est une mauvaise compréhension de ce que fait activate.
bin/activate est un script shell. Il place le répertoire bin du venv au début de PATH, définit VIRTUAL_ENV, enregistre les anciennes valeurs pour que deactivate puisse les restaurer et modifie l’invite de commande. Il ne contient rien que l’interpréteur lise lui-même. L’activation est simplement pratique pour une personne qui saisit python dans une invite de commande.
C’est le fichier de l’interpréteur que vous exécutez qui sélectionne réellement l’environnement. Lorsque /srv/myapp/.venv/bin/python démarre, le module Python site recherche un fichier pyvenv.cfg dans le répertoire qui contient l’exécutable, puis dans le répertoire parent. La présence de /srv/myapp/.venv/pyvenv.cfg définit sys.prefix sur le venv, ce qui place le site-packages de ce venv dans sys.path. C’est tout le mécanisme. Il ne nécessite ni variable d’environnement ni shell.
Cette unité ne démarre donc jamais :
[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 n’est pas une ligne de commande shell. systemd exécute directement un programme. Il n’existe donc pas de builtin source, && est transmis comme argument littéral et aucune expansion du shell n’a lieu, à l’exception des quelques expansions documentées par systemd lui-même.
Cette unité démarre, puis s’arrête :
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: No module named 'flask'/usr/bin/python3 est l’interpréteur système et son sys.path n’a jamais contenu votre venv. La même commande fonctionne dans votre session SSH uniquement parce que vous y aviez activé le venv. Le shell résolvait donc python3 via PATH vers .venv/bin/python3.
Entourer la commande avec /bin/bash -c 'source ... && gunicorn ...' fonctionne. Cela ajoute toutefois un shell entre systemd et votre processus sans aucun avantage, alors qu’un chemin absolu suffit :
[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 devrait afficher active (running) avec un Main PID correspondant à votre processus gunicorn. Dans le cas contraire, consultez le journal.
La ligne Environment=PATH= n’est pas nécessaire pour ExecStart, qui contient déjà un chemin complet. Elle concerne les processus démarrés par votre application. Un service hérite d’un PATH par défaut limité fourni par systemd. Le code Python qui appelle subprocess.run(["ffmpeg", ...]), ou une commande d’administration qui lance un console script du venv, ne trouvera donc pas ce dont il a besoin. Placer le répertoire bin du venv en tête est la seule partie de activate réellement utilisée par un service. Vérifiez ce que l’unité a effectivement reçu avec systemctl show -p Environment myapp.
La même règle s’applique aux tâches planifiées. Sur Ubuntu, cron ne transmet pas à une tâche le PATH de votre shell ou du daemon. Sauf si la crontab définit elle-même PATH, chaque tâche reçoit la valeur par défaut compilée /usr/bin:/bin, et /etc/environment ne la remplace pas. Cette valeur ne contient jamais votre venv. Une ligne de crontab contenant python3 /srv/myapp/cleanup.py exécute donc l’interpréteur système et échoue avec ModuleNotFoundError à trois heures du matin. cron envoie l’erreur par e-mail au propriétaire de la crontab, ou à l’adresse MAILTO si vous en définissez une. Sur la plupart des serveurs, cela signifie une boîte aux lettres locale que personne ne consulte. Si aucun programme de messagerie n’est installé, cron abandonne la sortie et écrit uniquement No MTA installed, discarding output dans le journal système. Indiquez également le chemin absolu du venv à cet endroit. Pour envoyer cette sortie dans le journal et conserver un historique de la dernière exécution, un ensemble composé d’un service et d’un timer systemd utilise la même ligne ExecStart.
Docker remplace-t-il cette décision ?
Un conteneur possède son propre système de fichiers, la question change donc de forme plutôt que de disparaître. Dans une image officielle comme python:3.12-slim, Python est intégré à /usr/local et ne comporte aucun marqueur EXTERNALLY-MANAGED. Par conséquent, pip install en tant que root est la méthode prévue pour ajouter des paquets, et un venv n'apporte que peu d'intérêt. Si vous construisez FROM ubuntu:24.04 à la place, vous rencontrerez à nouveau externally-managed-environment à l'intérieur de l'image, pour la même raison que sur l'hôte : il s'agit de l'interpréteur de la distribution, qui contient le fichier marqueur de la distribution.
De nombreuses images utilisent encore un venv, car cela simplifie les builds multi-étapes. L'étape de construction installe les dépendances dans /opt/venv, et l'étape d'exécution copie uniquement ce répertoire, laissant les compilateurs de côté. Le problème de l'activation persiste. Une ligne RUN source /opt/venv/bin/activate n'affecte que le shell de cette couche de build ; au moment de l'exécution, le conteneur démarre donc sur l'interpréteur système et déclenche ModuleNotFoundError. Définissez ENV PATH="/opt/venv/bin:$PATH", ou indiquez à CMD le chemin absolu /opt/venv/bin/gunicorn. Il s'agit du même bug que celui rencontré avec systemd, mais dans un fichier différent.
Ainsi, un conteneur remplace la question de l'interpréteur, car l'image fige l'interpréteur et tout ce qu'il contient. Il ne remplace pas la question du verrouillage des versions. Une image construite à partir d'un requirements.txt non verrouillé résoudra des versions différentes le mois prochain ; cela signifie que le tag de l'image est reproductible, mais que le build qui l'a produit ne l'est pas. Un fichier de verrouillage comme uv.lock, ou un fichier requirements entièrement figé, est ce qui comble cette lacune, avec ou sans conteneur. Et lorsqu'une application tourne sur un VPS sous systemd, un conteneur déplace principalement cette décision dans un Dockerfile, puisque systemd redémarre déjà un processus défaillant et capture sa sortie dans le journal. Exécuter Docker sur un VPS se justifie pleinement lorsque vous souhaitez que l'image construite soit l'élément que vous déployez.
FAQ
Puis-je simplement utiliser pip install avec --break-system-packages ?
Pas sur un serveur qui doit rester opérationnel. Le flag fait exactement ce qu’il indique : il supprime la protection, et pip écrit dans /usr/local/lib/python3.12/dist-packages, qui passe avant le répertoire apt dans sys.path. Votre version prend alors le pas sur celle de la distribution pour chaque script système exécuté sous /usr/bin/python3. De son côté, apt considère toujours que sa propre version est installée. Le conflit reste donc indétecté jusqu’à la panne. Dans une image de conteneur que vous reconstruisez entièrement à chaque fois, les dommages restent limités à cette image. L’utilisation de ce flag peut donc se justifier dans ce cas. Sur une machine que vous administrez, créez un venv. Une seule commande suffit.
Où placer l’environnement virtuel sur un serveur ?
Dans le répertoire de l’application elle-même, par exemple sous /srv/myapp/.venv, avec un deploy user comme propriétaire. Le compte de service doit disposer uniquement des droits de lecture et d’exécution. Utilisez un venv par application. Avec un environnement partagé, une mise à niveau pour la première application peut casser la deuxième. Ne déplacez pas et ne copiez pas un venv après sa création : chaque entry-point script de son répertoire bin/ contient ce chemin absolu dans sa ligne shebang. Un venv déplacé échoue donc avec bad interpreter: No such file or directory. Supprimez-le et recréez-le depuis requirements.txt.
Pourquoi mon service systemd échoue-t-il avec ModuleNotFoundError ?
Parce que l’unité exécute un interpréteur qui n’est pas celui du venv. Exécutez systemctl cat myapp et consultez ExecStart. Celui-ci doit désigner /srv/myapp/.venv/bin/python ou un console script du même répertoire bin/, en utilisant un chemin absolu. Sourcer directement activate dans ExecStart ne peut pas fonctionner, car ExecStart n’est pas un shell. systemd signale alors Failed to locate executable source avec status=203/EXEC. Ajoutez Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin afin que tous les sous-processus lancés par votre code trouvent également les outils du venv.
Dois-je utiliser uv plutôt que venv et pip ?
Utilisez uv si vous avez besoin d’un lockfile, si la durée d’installation est suffisamment longue pour vous gêner ou si vous avez besoin d’une version de Python que votre distribution ne fournit pas. uv crée un venv standard. L’unité systemd et l’organisation des fichiers ne changent donc pas, et uv sync --frozen installe exactement ce que le lockfile indique. Si une application est déployée depuis git avec un requirements.txt épinglé et que l’installation se termine en quelques secondes, python3 -m venv suffit déjà. Cela fait un binaire de moins à maintenir à jour sur le serveur.