Bibliothèques Python propres aux notebooks

Les bibliothèques délimitées aux notebooks vous permettent de créer, modifier, enregistrer, réutiliser et partager des environnements Python personnalisés qui sont spécifiques à un notebook. Lorsque vous installez une bibliothèque propre au notebook, seuls le notebook actuel et les tâches associées à ce notebook ont accès à cette bibliothèque. Les autres notebooks attachés au même cluster ne sont pas concernés.

Les bibliothèques propres au notebook ne persistent pas d’une session à l’autre. Vous devez réinstaller les bibliothèques délimitées aux notebooks au début de chaque session ou chaque fois que le notebook est détaché d’un cluster.

Databricks recommande d’utiliser la commande magique %pip pour installer des bibliothèques Python propres au notebook. Sur les notebooks serverless exécutant la version 5 de l’environnement ou une version ultérieure, vous pouvez également utiliser %uv pip pour des installations plus rapides.

Vous pouvez utiliser %pip dans les notebooks planifiés en tant que travaux. Si vous devez gérer l’environnement Python dans un notebook Scala, SQL ou R, utilisez la commande magic %python conjointement avec %pip.

Vous pouvez observer une augmentation du trafic vers le nœud driver lors de l’utilisation d’installations de bibliothèques limitées au notebook. Consultez les recommandations concernant la taille des nœuds de pilote.

Pour installer des bibliothèques pour tous les notebooks attachés à un cluster, utilisez des bibliothèques de cluster. Consultez les bibliothèques délimitées par le calcul.

Pour obtenir une vue d’ensemble complète des options disponibles pour installer des bibliothèques Python dans Databricks, consultez la gestion de l’environnement Python.

Gérer les bibliothèques avec les commandes %pip

La commande %pip est équivalente à la commande pip et prend en charge la même API. Les sections suivantes présentent des exemples de la façon dont vous pouvez utiliser les commandes %pip pour gérer votre environnement. Pour plus d’informations sur l’installation de packages Python avec pip, consultez la documentation d’installation pip et les pages associées.

Installations plus rapides avec %uv pip

La %uv pip commande magique est une alternative plus rapide à %pip. %uv pip fonctionne avec le gestionnaire de paquets uv et partage le même environnement virtuel du notebook que %pip, de sorte que les paquets installés avec l’un des outils sont visibles dans l’autre.

%uv pip est plus rapide que %pip pour les installations et les opérations en lecture seule telles que list. Cela le rend bien adapté à l’itération à partir d’une spécification d’environnement.

%uv pipprend en charge les sous-commandes standard pip : install, , uninstalllist, show, freeze, checket tree.

%uv pip install simplejson

%uv pip list

D’autres modèles d’installation sur cette page (volumes, fichiers d’espace de travail, fichiers de configuration requise, contrôle de version, référentiels privés) fonctionnent avec %uv pip. Vous pouvez remplacer %pip%uv pip par l’un de ces exemples.

%uv pip Limitations

• %uv pip uninstall ne peut pas supprimer entièrement les bibliothèques préinstallées dans l’environnement serverless. Seules les métadonnées du package sont supprimées. Les fichiers sous-jacents restent sur le système de fichiers et le package est toujours importable.
• %uv pip ne vérifie pas les conflits de dépendances par rapport aux bibliothèques préinstallées.
• Après l’exécution des commandes %uv pip, le panneau latéral Environnement du notebook peut afficher certaines bibliothèques préinstallées comme installées par l’utilisateur. Il s’agit d’un problème d’affichage et n’affecte pas les fonctionnalités du package.
• %uv pip est destiné à une itération interactive rapide. Pour configurer un environnement reproductible pour le notebook, ajoutez des dépendances dans le panneau latéral Environnement du notebook.

Installer une bibliothèque avec %pip

%pip install matplotlib

Installer un paquet wheel Python avec %pip

%pip install /path/to/my_package.whl

Désinstaller une bibliothèque avec %pip

%pip uninstall -y matplotlib

L’option -y est obligatoire.

Installer une bibliothèque à partir d’un système de gestion de version avec %pip

%pip install git+https://github.com/databricks/databricks-cli

Vous pouvez ajouter des paramètres à l’URL pour spécifier des éléments tels que la version ou le sous-répertoire git. Pour plus d’informations et pour obtenir des exemples d’utilisation d’autres systèmes de gestion de version, consultez la Prise en charge VCS.

Installer un package privé avec des informations d’identification gérées par des secrets Databricks avec %pip

pip prend en charge l’installation de packages à partir de sources privées avec authentification basique, y compris les systèmes de contrôle de version privés et les référentiels de packages privés, tels que Nexus et Artifactory. La gestion des secrets est disponible via l’API Databricks Secrets, qui vous permet de stocker des jetons d’authentification et des mots de passe. Utilisez l'API DBUtils pour accéder aux secrets depuis votre notebook. Notez que vous pouvez utiliser $variables dans les commandes magiques.

Pour installer un package à partir d’un dépôt privé, spécifiez l’URL du référentiel avec l'option --index-url sur %pip install ou ajoutez-la au fichier de configuration pip à l’emplacement ~/.pip/pip.conf.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

De même, vous pouvez utiliser la gestion des secrets avec les commandes magiques pour installer des packages privés à partir de systèmes de contrôle de version.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Installer un package à partir de DBFS avec %pip

Vous pouvez utiliser %pip pour installer un package privé qui a été enregistré sur DBFS.

Lorsque vous chargez un fichier sur DBFS, il renomme automatiquement le fichier, en remplaçant les espaces, les points et les traits d’union par des traits de soulignement. Pour les fichiers wheel pour Python, pip exige que le nom du fichier comporte des points dans le numéro de version (par exemple, 0.1.0) et des traits d’union à la place des espaces ou des caractères de soulignement ; ces noms de fichiers ne sont donc pas modifiés.

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

Installer un package à partir d’un volume avec %pip

Avec Databricks Runtime version 13.3 LTS (et les versions ultérieures), vous pouvez utiliser %pip pour installer un package privé enregistré sur un volume.

Lorsque vous chargez un fichier sur un volume, il renomme automatiquement le fichier, en remplaçant les espaces, les points et les traits d’union par des traits de soulignement. Pour les fichiers wheel Python, pip exige que le nom du fichier comporte des points dans le numéro de version (par exemple, 0.1.0) et des traits d’union au lieu d’espaces ou de caractères de soulignement, de sorte que ces noms de fichiers ne sont pas modifiés.

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

Installer un package stocké en tant que fichier d’espace de travail avec %pip

Avec Databricks Runtime 11.3 LTS et ultérieur, vous pouvez utiliser %pip pour installer un package privé qui a été enregistré en tant que fichier d’espace de travail.

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

Enregistrer des bibliothèques dans un fichier de spécifications

%pip freeze > /Workspace/shared/prod_requirements.txt

Tous les sous-répertoires du chemin d’accès au fichier doivent déjà exister. Si vous exécutez %pip freeze > /Workspace/<new-directory>/requirements.txt, la commande échoue si le répertoire /Workspace/<new-directory> n’existe pas déjà.

Utiliser un fichier de spécifications pour installer les bibliothèques

Un fichier de spécifications contient une liste de packages à installer à l’aide pip. Voici un exemple d’utilisation d’un fichier de spécifications :

%pip install -r /Workspace/shared/prod_requirements.txt

Consultez Format du fichier de spécifications pour plus d’informations sur les fichiers requirements.txt.

Recommandations concernant la taille des nœuds pilotes

L’utilisation de bibliothèques propres au notebook peut entraîner davantage de trafic vers le nœud pilote, car celui-ci doit s’efforcer de maintenir la cohérence de l’environnement entre les nœuds exécuteurs.

Lorsque vous utilisez un cluster de 10 nœuds ou plus, Databricks recommande ces spécifications en tant que configuration minimale requise pour le nœud de pilote :

• Pour un cluster UC de 100 nœuds, utilisez Standard_D8ds_v5.
• Pour un cluster GPU à 10 nœuds, utilisez Standard_NC12.

Pour les clusters de plus grande taille, utilisez un nœud de pilote plus grand.

Différences entre %pip, %sh pipet !pip

%sh et ! exécutent une commande shell dans un notebook\u00a0; la première est une commande magique auxiliaire de Databricks, tandis que la seconde est une fonctionnalité d’IPython. pip est une abréviation de %pip quand automagic est activé, ce qui correspond à la valeur par défaut dans les notebooks Python Azure Databricks.

À partir de Databricks Runtime 11.3 LTS et versions ultérieures, %pip, %sh pip et !pip permettent tous d’installer une bibliothèque en tant que bibliothèque Python à portée du notebook. Dans Databricks Runtime 10.4 LTS et les versions antérieures, Databricks recommande d’utiliser uniquement %pip ou pip pour installer les bibliothèques spécifiques à un notebook. Le comportement de %sh pip et !pip n’est pas cohérent dans Databricks Runtime 10.4 LTS et les versions antérieures.

Problèmes connus

• Sur Databricks Runtime 9.1 LTS, les bibliothèques propres au notebook sont incompatibles avec les tâches de streaming par lots. Databricks recommande d’utiliser des bibliothèques de cluster ou le noyau IPython à la place.