pyenv
Gère des versions de Python, pas des paquets. Fonctionne par shims : de faux
exécutables placés très tôt dans le PATH, qui redirigent vers la version active.
Voir et installer
pyenv versions # installées, l'active marquée d'une étoile
pyenv version # l'active ICI, et qui l'a décidée
pyenv install --list | rg "^\s*3\.12"
pyenv install 3.12.9
pyenv version
3.12.9 (set by /Users/edouard/code/mon-projet/.python-version)
La deuxième partie est la plus utile : elle dit quel fichier impose la version.
Choisir une version
pyenv global 3.12.9 # défaut de la machine -> ~/.pyenv/version
pyenv local 3.12.9 # ce dossier -> ./.python-version
pyenv shell 3.12.9 # ce shell seulement -> $PYENV_VERSION
pyenv local --unset
Ordre de priorité : shell > local > global.
Environnements nommés (plugin pyenv-virtualenv)
pyenv virtualenv 3.12.9 mon-env # -> ~/.pyenv/versions/3.12.9/envs/mon-env
pyenv local mon-env # activation automatique en entrant dans le dossier
pyenv activate mon-env
pyenv deactivate
pyenv virtualenv-delete mon-env
Ils vivent dans ~/.pyenv/versions/, pas dans le projet. C'est la différence de fond
avec un .venv local.
venv standard, sans le plugin
pyenv local 3.12.9
python -m venv .venv
source .venv/bin/activate
pip install httpx pydantic
pip freeze > requirements.txt
deactivate
Les deux pièges qui coûtent des minutes
Le shim répond à la place du venv. Un paquet installé dans le venv, et pourtant la commande résolue est celle de pyenv :
which uvicorn
/Users/edouard/.pyenv/versions/lewagon/bin/uvicorn
Contournement immédiat : python -m uvicorn main:app passe par le Python courant et ignore
le PATH. Sinon hash -r (zsh : rehash) vide le cache de commandes du shell.
La commande existe ailleurs. Message classique :
pyenv: jupyter: command not found
The `jupyter' command exists in these Python versions:
3.12.9/envs/lewagon
3.10.6/envs/taxifare-env
Le shim cherche dans la version active, qui n'a pas le paquet. Soit on active le bon
environnement, soit on passe par uv run.
Diagnostic
which -a python python3 # tous les candidats, dans l'ordre du PATH
pyenv which python # ce que pyenv résoudrait
pyenv doctor # si le plugin est installé
PYENV_VERSION=system python -V # contournement ponctuel
Rapport avec uv
uv est indépendant : il télécharge ses propres interpréteurs dans
~/.local/share/uv/python/ et ne consulte jamais pyenv. Seul point de friction : les deux
lisent .python-version.