Création et utilisation d'un wheelhouse pour les installations Python hors ligne
Un wheelhouse est un répertoire de wheels pré-compilés créé sur une machine avec accès réseau et installé hors ligne sur une machine cible. Le processus implique de figer un fichier requirements, d'utiliser pip wheel, d'archiver avec tar, puis d'installer avec --no-index --no-deps --force-reinstall.
Dans ce guide
La réponse courte
Un wheelhouse est un répertoire de fichiers wheel pré-construits que vous créez sur une machine disposant d'un accès réseau, puis que vous transférez vers une machine cible isolée. La machine de construction lit un fichier de dépendances figées, exécute pip wheel avec l'option --wheel-dir pour compiler chaque dépendance, et emballe le répertoire avec tar. Sur la machine cible, vous extrayez l'archive et lancez pip install avec les drapeaux --no-index --no-deps --force-reinstall afin que pip ne contacte jamais PyPI et n'installe que les wheels groupés. La vérification par hachage peut être ajoutée en incluant des entrées --hash dans le fichier requirements, ce qui vérifie l'intégrité des paquets lors de l'étape de construction. Cette méthode est appropriée lorsque la cible n'a pas d'accès réseau, que vous souhaitez éviter la recompilation sur la cible, et que vous pouvez contrôler l'OS et l'architecture. Ce n'est pas un substitut à un index privé car l'archive est un instantané statique, est généralement spécifique à l'OS et à l'architecture, et ne fournit pas de disponibilité continue ni de contrôle d'accès.
Construction du wheelhouse avec pip wheel
Le flux de travail principal commence par un fichier requirements figé. Exécutez python -m pip wheel -r requirements.txt --wheel-dir=/tmp/wheelhouse pour compiler chaque dépendance en un wheel et le stocker dans le répertoire wheelhouse. La machine de construction effectue la compilation, donc la machine cible n'a pas besoin de compilateur ou d'outils de construction. Une fois la commande terminée, le répertoire wheelhouse contient un fichier wheel par paquet, y compris les dépendances transitives. L'étape suivante consiste à archiver ce répertoire pour pouvoir le transférer. Sur un système Unix moderne, exécutez tar -cjvf wheelhouse.tar.bz2 -C /tmp/wheelhouse . pour créer une archive compressée unique. L'archive est ce que vous expédiez vers l'environnement isolé. Le fichier requirements est l'entrée de cette étape, il doit donc être exact et complet avant la construction.
mkdir -p /tmp/wheelhouse && python -m pip wheel -r requirements.txt --wheel-dir=/tmp/wheelhouse && tar -cjvf wheelhouse.tar.bz2 -C /tmp/wheelhouse .Conseil pratique
Générez le fichier requirements avec pip freeze sur la machine de construction, puis vérifiez que le fichier figé contient toutes les dépendances transitives avant d'exécuter pip wheel. Cela évite que des paquets manquants ne provoquent l'échec d'une installation hors ligne.
Installation depuis le wheelhouse sans accès réseau
Sur la machine cible, extrayez l'archive dans un répertoire temporaire, puis lancez pip install avec trois drapeaux importants. --no-index indique à pip de ne contacter aucun index de paquets, empêchant ainsi tout recours à PyPI. --no-deps empêche pip de résoudre ou d'installer des dépendances en dehors du lot, ce qui est sans risque car le fichier requirements liste déjà tous les paquets. --force-reinstall garantit que les wheels groupés sont installés même si une version correspondante est déjà présente. La commande python -m pip install --force-reinstall --no-index --no-deps /tmp/wheelhouse/* installe tous les wheels du répertoire extrait. Cette séquence permet une véritable installation hors ligne car aucune requête réseau n'est effectuée lors de l'étape d'installation. Le fichier requirements doit déjà contenir chaque dépendance transitive, sinon --no-deps laissera l'environnement incomplet.
tar -xvf wheelhouse.tar.bz2 -C /tmp/wheelhouse && python -m pip install --force-reinstall --no-index --no-deps /tmp/wheelhouse/*Préparation d'un fichier requirements figé
Un wheelhouse est construit à partir d'un fichier requirements avec des versions figées exactes. Vous pouvez générer ce fichier avec pip freeze, qui enregistre les paquets installés dans l'environnement actuel, y compris les dépendances transitives, et pas seulement les paquets de premier niveau. Chaque ligne utilise l'opérateur == pour exiger une version spécifique, par exemple SomePackage == 1.2.3. Le figement vous protège des bugs ou des incompatibilités dans les versions nouvellement publiées car pip ne mettra rien à jour pendant les étapes de construction ou d'installation. Le fichier requirements est l'entrée de l'étape de construction des wheels, il doit donc être complet et précis avant de lancer pip wheel. Si le fichier omet une dépendance transitive, l'installation hors ligne échouera car --no-deps empêche pip de la récupérer depuis un index. Examinez le fichier généré pour vous assurer qu'il inclut toutes les dépendances transitives avant de lancer pip wheel.
Archivage du wheelhouse pour le transfert
Une fois le répertoire wheel rempli, convertissez-le en une archive portable unique à l'aide de tar. La commande tar -cjvf wheelhouse.tar.bz2 -C /tmp/wheelhouse . crée une archive tar compressée contenant tous les fichiers wheel. Cette archive est ce qui est transféré vers l'environnement isolé. L'archive est un instantané statique de l'état de la machine de construction, préservant ainsi les paquets compilés exacts et leurs versions. Elle n'inclut pas de scripts de construction ou de code source, seulement les wheels prêts à être installés. L'archive doit être transférée sur la machine cible avant que l'installation ne puisse commencer. Comme l'archive est un fichier unique, elle est facile à déplacer entre les machines, mais elle n'est pas portable entre différents systèmes d'exploitation ou architectures CPU.
Ajout de la vérification par hachage au flux de travail
La vérification par hachage peut être combinée à la méthode du wheelhouse car les deux utilisent un fichier requirements. Vous ajoutez des entrées --hash au fichier requirements, par exemple FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824. Ces hachages sont vérifiés lorsque pip wheel télécharge les paquets, ce qui protège contre une compromission de l'index source ou de la chaîne de certificats HTTPS. Cela protège également contre la modification d'un paquet sans changement de son numéro de version sur les index qui le permettent. C'est une couche d'intégrité ajoutée au lot hors ligne. Les hachages doivent être valides et correspondre aux paquets de l'archive. Si les hachages ne correspondent pas, pip refusera d'utiliser le paquet, protégeant ainsi la construction contre des modifications silencieuses. Le mode de vérification par hachage est une couche d'intégrité, et non une alternative simplifiée à l'exécution d'un serveur d'index privé, car il ne fournit pas les avantages de disponibilité d'un index privé ou d'une bibliothèque vendored.
Déclaration des dépendances de construction dans pyproject.toml
La table [build-system] dans pyproject.toml déclare les dépendances au niveau Python qui doivent être installées pour exécuter le système de construction du projet. La clé requires liste ces dépendances, par exemple requires = [setuptools]. Ces exigences au moment de la construction influencent ce que pip wheel compile car le backend de construction en a besoin pour créer le wheel. Comprendre cette table aide à s'assurer que le wheelhouse capture toutes les dépendances d'outils de construction nécessaires pour que la compilation réussisse sur la machine de construction. Si le système de construction nécessite des paquets supplémentaires, ils doivent être listés dans requires afin que la machine de construction puisse les installer avant d'exécuter pip wheel. La sémantique par défaut s'applique lorsqu'aucun fichier pyproject.toml n'est présent, mais une table explicite rend les exigences de construction claires et reproductibles.
Limites de portabilité et insuffisance du wheelhouse
Un wheelhouse contient des paquets compilés qui sont généralement spécifiques à l'OS et à l'architecture, donc les archives ne sont pas nécessairement portables entre les machines. Le même wheel ne fonctionnera pas sur un système d'exploitation ou une architecture CPU différente sans recompilation. Cette méthode nécessite également une machine de construction avec accès réseau ; elle n'est d'aucune aide si aucune machine ne peut atteindre PyPI. Un wheelhouse ne remplace pas un index privé lorsque vous avez besoin d'un support multiplateforme ou d'une piste d'audit vivante au-delà d'une archive statique. La vérification par hachage seule fournit l'intégrité mais pas la disponibilité, et un wheelhouse fournit la disponibilité uniquement pour les paquets et plateformes exacts qu'il contient. Si vous devez supporter plusieurs plateformes, vous devez construire des wheelhouses distincts pour chaque environnement cible. L'archive est un instantané, pas un service, elle ne peut donc pas fournir de disponibilité continue ou de contrôle d'accès.
Quand le wheelhouse est l'outil approprié
Un wheelhouse est l'outil approprié lorsque l'environnement cible n'a pas d'accès réseau à PyPI, que vous voulez éviter une recompilation fastidieuse sur la machine cible, et que vous pouvez contrôler l'OS et l'architecture. Il regroupe tout le travail de compilation dans une seule archive, ce qui est distinct du simple figement de versions ou de l'utilisation seule de la vérification par hachage. Le figement protège contre les bugs des nouvelles versions, et la vérification par hachage ajoute l'intégrité, mais aucun des deux ne fournit la disponibilité ou la commodité d'installation hors ligne d'un wheelhouse. Le wheelhouse est un lot de wheels pré-construits que la machine cible installe sans contacter aucun index. Cette approche fonctionne entre les OS et architectures uniquement lorsque la machine de construction et la machine cible partagent la même plateforme. C'est une solution pratique pour les déploiements isolés où l'accès réseau est indisponible ou restreint.
Points à vérifier
- Le fichier requirements doit figer chaque paquet avec == et inclure les dépendances transitives, pas seulement les paquets de premier niveau.
- La machine de construction doit avoir un accès réseau pour télécharger et compiler toutes les dépendances avant l'archivage.
- La machine cible doit utiliser le même OS et la même architecture CPU que la machine de construction pour que les wheels soient compatibles.
- La commande d'installation doit inclure --no-index, --no-deps et --force-reinstall pour empêcher l'accès réseau et la résolution de dépendances externes.
- L'archive doit être créée à partir du répertoire wheel avec tar avant le transfert, et extraite avant l'installation.
- Les entrées de vérification par hachage dans le fichier requirements doivent être valides et correspondre aux paquets de l'archive.
- Le wheelhouse contient des paquets compilés et n'est pas portable entre différents systèmes d'exploitation ou architectures.
- Un wheelhouse ne remplace pas un index privé pour la disponibilité continue, le contrôle d'accès ou la gestion d'audit.
Champ d’application
Un wheelhouse contient des paquets compilés qui sont généralement spécifiques à l'OS et à l'architecture, donc les archives ne sont pas nécessairement portables entre les machines. L'approche nécessite une machine de construction avec accès réseau ; elle n'est pas utile si aucune machine ne peut atteindre PyPI. Les wheels compilés peuvent contenir du code binaire spécifique à la plateforme, donc la compilation croisée n'est pas supportée par cette seule méthode. L'archive est un instantané statique et ne fournit pas de disponibilité continue ni de gestion ACL comme un serveur d'index privé. L'utilisation de --no-deps signifie que l'opérateur doit s'assurer que le fichier requirements liste déjà toutes les dépendances transitives.