Gestionnaire de paquet Python 4/4

Par / 
python -m pip download package -d downloads/

Télécharger uniquement une wheel :

python -m pip download --only-binary=:all: package -d downloads/

Afficher les informations :

python -m pip index versions package

Installer avec davantage de détails :

python -m pip install -vvv package

68. Hashes

Un fichier de dépendances peut inclure des hashes :

requests==2.32.3 \
    --hash=sha256:...

Installation stricte :

python -m pip install --require-hashes -r requirements.txt

Cela permet de vérifier que les fichiers téléchargés correspondent exactement aux artefacts attendus.

Partie 20 — Workflow professionnel recommandé

69. Workflow minimal avec venv et pip

Windows

mkdir mon-projet
cd mon-projet

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install fastapi uvicorn

python -m pip freeze > requirements.txt

Pour recréer :

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

70. Workflow recommandé avec uv

uv init mon-projet
cd mon-projet

uv python pin 3.12
uv add fastapi uvicorn
uv add --dev pytest ruff

uv run pytest
uv run uvicorn main:app --reload

Fichiers à versionner :

pyproject.toml
uv.lock
.python-version
src/
tests/

À ignorer :

.venv/
__pycache__/
.pytest_cache/
.ruff_cache/

71. Exemple de projet complet

mon-api/
├── .gitignore
├── .python-version
├── pyproject.toml
├── uv.lock
├── src/
│   └── mon_api/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

pyproject.toml :

[project]
name = "mon-api"
version = "0.1.0"
requires-python = ">=3.12,<3.13"

dependencies = [
    "fastapi>=0.115,<1",
    "uvicorn[standard]>=0.34,<1",
]

[dependency-groups]
dev = [
    "pytest>=8,<9",
    "ruff>=0.12,<1",
]

Commandes :

uv sync
uv run uvicorn mon_api.main:app --reload
uv run pytest
uv run ruff check .

Partie 21 — Procédure universelle de diagnostic

72. Étape 1 : identifier le Python

python --version
python -c "import sys; print(sys.executable)"

Sous Windows :

py --list
where python

Sous Linux :

type -a python
type -a python3

73. Étape 2 : identifier pip

python -m pip --version

Comparer son chemin avec :

python -c "import sys; print(sys.executable)"

74. Étape 3 : identifier l’environnement

python -c "import sys; print('prefix:', sys.prefix); print('base:', sys.base_prefix); print('venv:', sys.prefix != sys.base_prefix)"

75. Étape 4 : vérifier la compatibilité

python -m pip index versions nom-du-paquet
python -m pip install -vvv nom-du-paquet

Lire notamment :

  • Requires-Python ;
  • les versions candidates ignorées ;
  • les wheels rejetées ;
  • les conflits de dépendances.

76. Étape 5 : tester la disponibilité d’une wheel

python -m pip install --only-binary=:all: nom-du-paquet

Si cela échoue mais que l’installation normale tente de compiler, aucune wheel compatible n’est probablement disponible.

77. Étape 6 : inspecter les tags

python -m pip debug --verbose

Comparer avec le fichier téléchargé :

cp312-cp312-win_amd64

78. Étape 7 : repartir proprement

deactivate

Supprimer .venv, puis :

python-version-voulue -m venv .venv

Réinstaller depuis le fichier de dépendances.

Partie 22 — Les règles à retenir

79. Les dix règles essentielles

Règle 1

Un environnement virtuel ne télécharge pas automatiquement une autre version de Python.

Il utilise le Python qui le crée.

Règle 2

Toujours préférer :

python -m pip

à :

pip

Règle 3

Un environnement virtuel par projet.

Règle 4

Ne pas installer les dépendances de projet dans le Python global.

Règle 5

Ne pas utiliser sudo pip install.

Règle 6

Une wheel doit correspondre :

  • à l’implémentation Python ;
  • à la version Python ;
  • à l’ABI ;
  • au système ;
  • à l’architecture.

Règle 7

Une compilation déclenchée par pip signifie souvent qu’aucune wheel compatible n’a été trouvée.

Règle 8

Ne pas copier .venv entre machines.

Le recréer à partir des métadonnées.

Règle 9

Versionner :

pyproject.toml
fichier de lock
.python-version

mais pas :

.venv

Règle 10

Pour un nouveau projet, uv constitue aujourd’hui une solution très cohérente pour gérer simultanément Python, les environnements, les dépendances et le verrouillage.

Partie 23 — Arbre de décision rapide

Je veux commencer un projet

Ai-je une version Python imposée ?
│
├── Oui
│   └── Installer ou sélectionner cette version
│
└── Non
    └── Choisir une version stable supportée par les bibliothèques

Puis :

Projet moderne ?
│
├── Oui → uv + pyproject.toml + uv.lock
│
└── Non → venv + pip + requirements.txt

Une installation échoue

L’erreur parle de Requires-Python ?
│
├── Oui → mauvaise version de Python
│
└── Non
    │
    ├── ResolutionImpossible ?
    │   └── conflit de versions
    │
    ├── Failed building wheel ?
    │   └── compilation native ou absence de wheel
    │
    ├── unsupported wheel ?
    │   └── mauvais Python, OS ou architecture
    │
    └── ModuleNotFoundError après installation ?
        └── pip et python ne visent pas le même environnement

Commande de diagnostic finale

Sous Windows PowerShell :

Write-Host "=== Python ==="
python --version
python -c "import sys, platform; print('Executable:', sys.executable); print('Prefix:', sys.prefix); print('Base prefix:', sys.base_prefix); print('Virtual env:', sys.prefix != sys.base_prefix); print('Implementation:', platform.python_implementation()); print('Machine:', platform.machine())"

Write-Host "`n=== pip ==="
python -m pip --version

Write-Host "`n=== Paths ==="
where.exe python
where.exe pip

Write-Host "`n=== Packages ==="
python -m pip list

Sous Linux ou macOS :

echo "=== Python ==="
python --version
python -c "import sys, platform; print('Executable:', sys.executable); print('Prefix:', sys.prefix); print('Base prefix:', sys.base_prefix); print('Virtual env:', sys.prefix != sys.base_prefix); print('Implementation:', platform.python_implementation()); print('Machine:', platform.machine())"

echo
echo "=== pip ==="
python -m pip --version

echo
echo "=== Paths ==="
type -a python
type -a pip

echo
echo "=== Packages ==="
python -m pip list

La sortie de ces commandes permet de résoudre la majorité des problèmes de gestion de paquets Python.

Retour en haut