Reading Time: 10 minutes

La gestion des dépendances en python scientifique est l’une des parties les plus importantes de la recherche reproductible. Une simulation peut échouer des mois plus tard, car les versions des packages ont changé, un interpréteur Python décalé ou une bibliothèque numérique mise à jour d’une manière qui affecte les résultats.

Ce guide explique comment les fichiers de verrouillage, les environnements et les gestionnaires de paquets modernes aident les chercheurs à conserver des flux de travail scientifiques Python reproductibles, portables et plus faciles à entretenir.

Points à retenir clés

  • Les fichiers de verrouillage sont l’une des étapes les plus percutantes pour les flux de travail Scientific Python reproductibles.
  • uv est un gestionnaire de paquets moderne et rapide et est de plus en plus utilisé comme alternative au PIP, aux outils PIP et à la poésie.
  • PEP 751 introduit un format de fichier de verrouillage standardisé, pylock.toml, pour réduire la fragmentation de l’outil.
  • Conda reste important pour les projets scientifiques Python avec des dépendances non-Python telles que C, C++, MPI, HDF5 et CUDA.
  • Votre choix d’outil doit correspondre à votre flux de travail : uv pour la rapidité et la reproductibilité, Conda pour les piles scientifiques et HPC et la poésie pour les pipelines de publication matures.

Le mode de défaillance cachée en Python scientifique

Chaque chercheur en informatique scientifique voit finalement le même problème. Une simulation a fonctionné le mois dernier, mais elle échoue désormais avec une incompatibilité de version. Pire, il peut encore fonctionner mais produire des résultats subtilement différents.

Ce n’est pas seulement un inconvénient. C’est un échec de reproductibilité. L’environnement de calcul a changé, y compris les versions de package, les interpréteurs Python ou les dépendances de niveau inférieur. Votre code est cassé ou produit en silence des résultats qui ne sont plus équivalents à l’exécution d’origine.

La cause profonde est généralement des dépendances non épinglées. Même lorsque le code est contrôlé en version, le travail reste lié à une machine spécifique et à un moment donné si l’environnement n’est pas reproductible.

Le python scientifique rend ce problème particulièrement grave. Contrairement à de nombreux projets Web, le calcul scientifique dépend souvent de chaînes complexes de bibliothèques numériques, de packages compilés et de constructions sensibles au matériel. NumPy, Scipy, Fipy, HDF5, MPI, OpenBlas et les versions spécifiques de Python doivent fonctionner ensemble.

La solution consiste à gérer délibérément les dépendances. Utilisez des fichiers de verrouillage pour geler les versions exactes, suivre les environnements dans le contrôle de version et documenter la façon dont l’environnement doit être recréé.

Qu’est-ce qu’un fichier de verrouillage ?

Un fichier de verrouillage est un instantané de l’environnement logiciel exact d’un projet. Il enregistre les versions spécifiques de toutes les dépendances, y compris les sous-dépendances, qui ont été installées lors de la dernière configuration du projet.

Considérez-le comme une recette congelée pour la configuration de votre logiciel. Tout le monde peut recréer le même environnement plus tard, même si les versions de packages ont changé en amont.

sans fichiers de verrouillage

# requirements.txt without a lockfile
numpy>=1.25.0
scipy>=1.11.0
fipy>=4.3.0

# On another machine or after a month:
pip install -r requirements.txt

# This might install newer versions:
# numpy 1.26.x, scipy 1.12.x, or different dependency builds

Ce type de configuration permet aux versions de package de changer. Le code peut toujours s’exécuter, mais le comportement numérique, la précision, le comportement du solveur ou les internes de dépendance peuvent changer.

avec des fichiers de verrouillage

# uv.lock or another lockfile records exact resolved versions

uv sync

# Anyone who runs the sync command gets the same resolved environment

Cela est important pour les projets de simulation, car les bibliothèques numériques peuvent modifier les chemins de code entre les versions. Le comportement à virgule flottante peut différer entre les builds. Les solveurs PDE et les cadres scientifiques peuvent également se comporter différemment d’une version à l’autre.

Un fichier de verrouillage réduit cette incertitude en rendant l’installation déterministe.

Le paysage de la gestion des dépendances Python

L’écosystème Python dispose de plusieurs options pratiques de gestion des dépendances. Chaque outil a des atouts différents, et le bon choix dépend de la question de savoir si le projet est pur Python, axé sur HPC, orienté package ou construit pour la reproductibilité à long terme.

UV : l’option rapide moderne

uv est un gestionnaire de packages basé sur la rouille construit par Astral. Il vise à remplacer plusieurs outils Python courants, notamment PIP, PIP-Tools, PIPX, PYENV et VirtualEnv, par un seul flux de travail rapide.

Les chercheurs passent à uv pour plusieurs raisons :

  1. vitesse. uv peut installer des packages beaucoup plus rapidement que les flux de travail traditionnels basés sur PIP, en particulier avec la mise en cache.
  2. Fichier de verrouillage universel. Un seul uv.lock peut prendre en charge les installations reproductibles sur toutes les plates-formes.
  3. Compatibilité PIP. Les commandes telles que uv pip install facilitent la migration.
  4. Gestion des versions Python. uv peut installer et gérer des interpréteurs Python, ce qui réduit le besoin d’outils distincts.
  5. Installation autonome. uv n’exige pas que Python soit installé en premier.

Utilisez uv pour de nouveaux projets où la vitesse, la reproductibilité et la simple migration de PIP Matter.

Il est particulièrement utile pour :

  • Nouveaux projets de simulation.
  • Pipelines CI/CD où l’heure d’installation est importante.
  • Les projets qui ont besoin de gestion des dépendances et de gestion des versions Python.
  • Les équipes migrent depuis PIP ou PIP-Tools.

Flux de travail UV de base

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new project with Python 3.11
uv init my-simulation --python 3.11
cd my-simulation

# Add dependencies
uv add numpy scipy fipy

# Generate a lockfile
uv lock

# Sync to install from the lockfile
uv sync

Le principal compromis est que la poésie a encore des flux de travail de publication mûrs et une gestion avancée des groupes de dépendances. Si vous maintenez un package scientifique Python pour Pypi, la poésie peut toujours être attrayante.

Poésie : le chef de projet établi

La poésie est un outil complet de gestion de projet. Il gère la résolution de dépendances, les environnements virtuels, la création de packages et la publication sur Pypi.

Les chercheurs choisissent toujours la poésie pour plusieurs raisons :

  1. groupes de dépendances. La poésie peut séparer proprement le développement, les tests, la documentation et les dépendances CI.
  2. Publication du workflow. Il dispose d’un support intégré pour la création et la publication de packages.
  3. Écosystème mûr. La poésie a des années d’utilisation de la production, une documentation approfondie et une grande communauté.

Utilisez de la poésie lorsque :

  • Vous publiez un package Python sur Pypi.
  • Vous avez besoin d’une gestion des groupes de dépendances à maturité
  • Votre équipe valorise une longue expérience et une documentation établie.

Le compromis est la vitesse. La poésie peut prendre plus de uv pour les installations froides, la génération de fichiers de verrouillage et les ajouts de packages. Pour les petits projets, cela n’a peut-être pas d’importance. Pour les grands projets et les pipelines CI, la différence peut devenir perceptible.

Conda : la base scientifique

Conda reste l’un des outils les plus importants pour Python scientifique, en particulier lorsque le projet a besoin de dépendances non-Python.

Conda est utile pour la recherche car il peut gérer les packages Python, les packages R, les bibliothèques compilées, les compilateurs, les MPI, HDF5, CUDA et d’autres dépendances au niveau du système dans un seul environnement.

Conda est important lorsque :

  • Vous avez besoin de dépendances non-Python telles que C, C++, MPI, HDF5, FFTW ou CUDA.
  • Vous ciblez les clusters HPC.
  • Vos bibliothèques scientifiques dépendent du code C ou Fortran compilé.
  • Vous travaillez à travers Python et R.

Le compromis est que Conda peut être plus lent que uv pour la résolution de dépendance pure-python et peut ne pas produire facilement des fichiers de verrouillage multi-plateformes universels.

Flux de travail Conda de base

# Create environment
conda create -n my-sim python=3.11
conda activate my-sim

# Install packages, including non-Python dependencies
conda install numpy scipy hdf5 openmpi

# Export to environment file
conda env export --no-builds | grep -v "prefix:" > environment.yml

# Restore the environment
conda env create -f environment.yml

PIP-Tools : l’option minimaliste

pip-tools Comble les flux de travail et les fichiers de verrouillage PIP traditionnels. Il est léger et reste proche de l’interface PIP.

Utilisez les outils PIP lorsque :

  • Vous voulez une approche simple.
  • Vous migrez à partir de PIP et ne souhaitez pas apprendre un outil plus grand.
  • Votre projet est petit et n’a pas besoin de groupes de dépendances avancés.

Le compromis est que PIP-Tools peut générer des fichiers de sortie spécifiques à la plate-forme. Il est également moins complet que la poésie ou uv.

PEP 751 : L’avenir des lockfiles

PEP 751 propose un format de fichier standardisé pour l’enregistrement des dépendances Python afin que les environnements puissent être installés de manière reproductible. Ce format est appelé pylock.toml.

Ce que ça résout

Les outils de dépendance Python ont toujours utilisé différents formats de fichier de verrouillage. PDM, PIP Freeze, PIP-Tools, Poetry et uv Tous les environnements approchent le verrouillage différemment.

Cela crée plusieurs problèmes :

  • Verrouillage du fournisseur. Il peut être difficile de basculer entre les outils.
  • Fragmentation des outils. Les scanners de sécurité et les outils d’automatisation peuvent prendre en charge uniquement certains formats.
  • difficulté d’audit. Différents formats ont une syntaxe et des conventions différentes.

PEP 751 propose pylock.toml comme format standardisé.

Pourquoi c’est important pour le python scientifique

Le format proposé est utile pour la recherche car il s’agit de :

  • Lisible par l’homme, en utilisant TOML.
  • générés par la machine, afin que les outils puissent écrire une sortie cohérente.
  • Consommable par des outils non Python.
  • Sécurisez par la conception, avec des hachages cryptographiques pour la protection de la chaîne d’approvisionnement.
  • Assez flexible pour représenter plusieurs environnements ou groupes de dépendance.

Une fois largement adopté, pylock.toml peut réduire le besoin de formats de fichier de verrouillage spécifiques à l’outil. Pour les chercheurs, cela signifie une meilleure interopérabilité. Un fichier de verrouillage peut être consommé par n’importe quel outil conforme et audité plus facilement par des services externes.

Le spectre de reproductibilité

La reproductibilité est un spectre. Le bon niveau dépend du risque, de la durée du projet et des exigences de publication.

Niveau Approche Coût reproductibilité le mieux pour
Bon Dépendances de documents dans Readme Minimale Vérification manuelle Scripts et tutoriels rapides
Mieux Fichier d’environnement tel que requirements.txt ou environment.yml Faible Installation automatisée Projets et collaborateurs partagés
Meilleur LockFile Plus Environnement contrôlé par la version Modérer reproduction exacte Publications et archives à long terme
Maximum Containerisation avec Docker ou Singularité Haut Forte isolation HPC et flux de travail publiés

Pour les projets de recherche, le minimum est de fixer des versions exactes dans requirements.txt ou environment.yml. L’approche recommandée consiste à utiliser uv lock ou à l’exportation Conda pour générer un fichier d’environnement reproductible. La meilleure pratique consiste à suivre ce fichier dans Git et à documenter comment recréer l’environnement dans le fichier README.

Flux de travail pratiques pour des projets scientifiques

Workflow 1 : nouveau projet de simulation avec UV

# Initialize project
uv init my-simulation --python 3.11
cd my-simulation

# Add core dependencies
uv add numpy scipy matplotlib

# Add scientific libraries
uv add fipy mpmath

# Generate lockfile
uv lock

# Add dev dependencies
uv add --group dev pytest black ruff

# Commit everything
git add pyproject.toml uv.lock
git commit -m "Initial project structure with pinned dependencies"

Cela fonctionne parce que le fichier uv.lock est validé dans Git. Toute personne clonant le référentiel et en cours d’exécution uv sync obtient les mêmes versions résolues.

Workflow 2 : Projet HPC avec Conda et Singularité

# On your workstation
conda create -n hpc-sim python=3.11
conda activate hpc-sim
conda install numpy scipy hdf5 openmpi

# Export environment
conda env export --no-builds | grep -v "prefix:" > environment.yml

# Build Singularity image from Docker
docker build -t my-sim:latest .
singularity build my-sim.sif docker://my-sim:latest

# Transfer to HPC cluster
scp my-sim.sif hpc-cluster:/scratch/

Cela fonctionne parce que Conda gère les dépendances sur le poste de travail, tandis que Singularity fournit une conteneurisation compatible HPC. Le fichier environment.yml peut être contrôlé en version et recréé sur un autre système.

Flux de travail 3 : migration du PIP vers les UV

# Start with existing requirements.txt
pip install uv

# Replace pip with uv for installs
uv pip install -r requirements.txt

# Generate a uv lockfile
uv lock

# From now on, use uv sync instead of pip install
uv sync

Ce chemin de migration est simple car uv est compatible avec de nombreux flux de travail de style PIP. Le fichier uv.lock devient la source unique de vérité pour l’environnement.

erreurs courantes et comment les éviter

Erreur 1 : Utilisation des dépendances non épinglées

# WRONG: Allows automatic updates
numpy>=1.0
scipy>=1.0

# RIGHT: Pin exact versions
numpy==1.26.4
scipy==1.11.4

Les modifications de version mineures peuvent modifier le comportement numérique, les critères de convergence ou la précision à virgule flottante. Épinglez les versions exactes lorsque la reproductibilité est importante.

Erreur 2 : Ne valider aucun fichier de verrouillage

Si votre référentiel contient pyproject.toml mais pas de fichier de verrouillage, votre projet n’est pas entièrement reproductible. Un fichier de verrouillage est l’exigence minimale pour les constructions déterministes.

Générez un fichier de verrouillage et validez-le :

uv lock  # or conda export
git add uv.lock  # or environment.yml
git commit -m "Add lockfile for reproducible environment"

Erreur 3 : ignorer les sous-dépendances

Même si vous épinglez des packages de niveau supérieur, les sous-dépendances peuvent toujours changer de comportement.

# If you pin fipy but not its dependencies:
# numpy, mpmath, and other packages may upgrade independently

Utilisez un outil qui résout et épingle l’arbre de dépendances complet, tel que uv, Conda ou Poésie.

Erreur 4 : environnements spécifiques à la plate-forme

Certains outils peuvent générer une sortie spécifique à la plate-forme. Si vous développez sur macOS mais que vous déployez sous Linux, les fichiers d’environnement peuvent échouer ou résoudre différemment.

Utilisez des outils qui prennent en charge les fichiers de verrouillage multi-plateformes ou générez des fichiers de verrouillage sur la plate-forme cible.

Erreur 5 : Dépendances de données externes

Si une simulation dépend d’API ou de bases de données externes qui changent, la reproductibilité peut s’arrêter même lorsque l’environnement Python est verrouillé.

Snapshot Données externes lorsque cela est possible. Si cela n’est pas possible, utilisez des points de terminaison d’API versionnés et documentez la version exacte ou la date d’accès.

Ce que nous recommandons : un cadre de décision

Utilisez ce cadre de décision lors du choix d’un outil de gestion de la dépendance pour un projet scientifique Python.

  1. Avez-vous besoin de dépendances non-Python telles que C, C++, MPI, CUDA, HDF5 ou FFTW ?

    • Oui : utilisez Conda ou utilisez Conda à l’intérieur de Docker ou Singularité.
    • Non : passez à la question suivante.

  2. Publiez-vous un package Python sur Pypi ?

    • Oui : envisagez la poésie pour les flux de travail d’édition matures ou uv pour la vitesse.
    • Non : passez à la question suivante.

  3. Travaillez-vous dans des pipelines CI/CD ?

    • Oui : utilisez uv car des installations plus rapides peuvent réduire le temps de CI.
    • Non : soit uv, Conda ou Poetry peut fonctionner selon le projet.

  4. Quelle est l’importance de la compatibilité multiplateforme ?

    • Élevé : utilisez uv lorsqu’un fichier de verrouillage universel répond à vos besoins.
    • Modéré : Conda peut bien fonctionner, en particulier sur les systèmes de recherche de type Unix.

Pour la plupart des nouveaux projets de recherche, uv est une valeur par défaut solide lorsque vous avez besoin de rapidité et de reproductibilité. Pour les projets HPC ou les workflows avec des dépendances non Python, associez Conda à la conteneurisation.

Résumé

La gestion des dépendances en Python scientifique n’est pas facultative. Il s’agit d’une base de recherche reproductible.

Les points les plus importants sont :

  1. Les fichiers de verrouillage sont essentiels. Épinglez les versions exactes et suivez-les dans Git.
  2. uv est une option moderne forte pour les environnements rapides et reproductibles.
  3. Conda reste vital pour les piles scientifiques avec des dépendances non python.
  4. PEP 751 vise à unifier les formats de fichier de verrouillage via pylock.toml.
  5. Un README avec des instructions d’installation claires est la documentation minimale dont chaque projet a besoin.

Commencez par auditer les projets en cours. Vérifiez si les environnements sont documentés et que les dépendances sont épinglées. Convertissez un projet pour utiliser un fichier de verrouillage. Le coût initial est payant lorsque vous ou un autre chercheur devez réexécuter la simulation des mois ou des années plus tard en toute confiance.

Guides connexes

Références et lectures complémentaires