Bibliothèques Python à l'échelle du Notebook
Les bibliothèques limitées à un Notebook vous permettent de créer, modifier, enregistrer, réutiliser et partager des environnements Python personnalisés spécifiques à un Notebook. Lorsque vous installez une bibliothèque limitée à un Notebook, seuls le Notebook actuel et les Jobs associés à ce Notebook ont accès à cette bibliothèque. D'autres notebooks associés au même cluster ne sont pas affectés.
Les bibliothèques limitées au Notebook ne persistent pas d'une session à l'autre. Vous devez réinstaller les bibliothèques à l'échelle du notebook 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 délimitées par un notebook. Sur les notebooks serverless exécutant la version 5 de l’environnement ou supérieure, vous pouvez également utiliser %uv pip pour des installations plus rapides.
Vous pouvez utiliser %pip dans les notebooks planifiés en tant que jobs. Si vous devez gérer l'environnement Python dans un Notebook Scala, SQL ou R, utilisez la commande magique %python conjointement avec %pip.
Vous pourriez rencontrer plus de trafic vers le nœud Driver lorsque vous travaillez avec des installations de bibliothèques limitées au notebook. Consultez Recommandations concernant la taille du nœud Driver.
Pour installer des bibliothèques pour tous les notebooks attachés à un cluster, utilisez les bibliothèques de cluster. Consultez les bibliothèques limitées au compute.
Pour un aperçu complet des options disponibles pour l'installation des bibliothèques Python dans Databricks, consultez 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 manière 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 pip install et les pages associées.
%piples commandes ne redémarrent pas automatiquement le processus Python. Si vous installez un nouveau package ou mettez à jour un package existant, vous devrez peut-être utiliserdbutils.library.restartPython()pour voir les nouveaux packages. Consultez Redémarrer le processus Python sur Databricks.- La mise à niveau, la modification ou la désinstallation de packages Python de base (tels qu'IPython) avec
%pippeut entraîner un dysfonctionnement de certaines fonctionnalités. Si vous rencontrez de tels problèmes, reset l'environnement en redémarrant le cluster ou en démarrant une nouvelle session.
Installations plus rapides avec %uv pip
%uv pip est uniquement disponible sur les Notebooks serverless exécutant la version 5 de l'environnement ou une version ultérieure. Le compute Classic et les versions antérieures de l'environnement Serverless ne prennent pas en charge %uv pip.
La commande magique %uv pip est une alternative plus rapide à %pip. %uv pip est alimenté par le gestionnaire de packages uv et partage le même environnement virtuel de Notebook que %pip, de sorte que les packages installés avec un outil sont visibles par 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 sur la base d'une spécification d'environnement.
%uv pip prend en charge les sous-commandes standard pip : install, uninstall, list, show, freeze, check et tree.
%uv pip install simplejson
%uv pip list
D'autres modèles d'installation sur cette page (volumes, fichiers Workspace, fichiers de configuration, contrôle de version, repositories privés) fonctionnent avec %uv pip. Vous pouvez remplacer %pip par %uv pip dans n'importe lequel de ces exemples.
%uv pip limitations
%uv pip uninstallne peut pas entièrement supprimer les bibliothèques préinstallées sur 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 pipne vérifie pas les conflits de dépendances avec les bibliothèques préinstallées.- Après l'exécution de
%uv pipcommandes, 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 qui n’affecte pas la fonctionnalité du package. %uv pipest destiné à une itération interactive rapide. Pour configurer un environnement reproductible pour le notebook, ajoutez les dépendances dans le panneau latéral Environnement du notebook.
Installer une bibliothèque avec %pip
%pip install matplotlib==3.8.4
Installer un package Python wheel avec %pip
%pip install /path/to/my_package.whl
Désinstaller une bibliothèque avec %pip
Vous ne pouvez pas désinstaller une bibliothèque incluse dans les notes de version et la compatibilité de Databricks Runtime ou une bibliothèque installée en tant que bibliothèque de cluster. Si vous avez installé une version de bibliothèque différente de celle incluse dans Databricks Runtime ou de celle installée sur le cluster, vous pouvez utiliser %pip uninstall pour rétablir la bibliothèque à la version default dans Databricks Runtime ou à la version installée sur le cluster, mais vous ne pouvez pas utiliser une commande %pip pour désinstaller la version d'une bibliothèque incluse dans Databricks Runtime ou installée sur le cluster.
%pip uninstall -y matplotlib
L'option -y est requise.
Installer une bibliothèque à partir d'un système de contrôle 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 comme la version ou le sous-répertoire Git. Consultez la prise en charge de VCS pour plus d’informations et pour des exemples utilisant d’autres systèmes de contrôle de version.
Installez un package privé avec des identifiants gérés par les secrets Databricks avec %pip
pip prend en charge l'installation de packages à partir de sources privées avec l'authentification de base, y compris les systèmes de contrôle de version privés et les repository 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 repository privé, spécifiez l'URL du repository avec l'option --index-url vers %pip install ou ajoutez-le 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 des 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
Tout utilisateur de Workspace peut modifier les fichiers stockés dans DBFS. Databricks recommande de stocker les fichiers dans des workspaces ou sur des volumes Unity Catalog.
Vous pouvez utiliser %pip pour installer un package privé qui a été enregistré sur DBFS.
Lorsque vous upload un fichier vers 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 Python wheel, pip exige que le nom du fichier utilise des points dans la version (par exemple, 0.1.0) et des traits d'union au lieu d'espaces ou de traits de soulignement, ainsi, ces noms de fichier ne sont pas modifiés.
%pip install /Volumes/<catalog>/<schema>/<volume>/mypackage-0.0.1-py3-none-any.whl
Installer un package à partir d’un volume avec %pip
Aperçu
Cette fonctionnalité est en aperçu public.
Avec Databricks Runtime 13.3 LTS et versions supérieures, vous pouvez utiliser %pip pour installer un package privé qui a été enregistré sur un volume.
Lorsque vous upload un fichier vers un volume, celui-ci renomme automatiquement le fichier, en remplaçant les espaces, les points et les tirets par des tirets bas. Pour les fichiers Python wheel, pip exige que le nom du fichier utilise des points dans la version (par exemple, 0.1.0) et des traits d'union au lieu d'espaces ou de traits de soulignement, ainsi, ces noms de fichier 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 workspace avec %pip
Avec Databricks Runtime 11.3 LTS et versions ultérieures, vous pouvez utiliser %pip pour installer un package privé qui a été enregistré en tant que fichier de Workspace.
%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl
Enregistrer les bibliothèques dans un fichier de prérequis
%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à.
Utilisez un fichier de spécifications pour installer les bibliothèques
Un fichier de requirements contient une liste de packages à installer à l’aide de pip. Voici un exemple d’utilisation d’un fichier de requirements :
:::note Compatibilité Serverless
Nous vous recommandons de ne plus utiliser les commandes %pip install non épinglées, car elles ne sont pas compatibles avec l'architecture de compute Serverless de Databricks. Utilisez pin to ==<version> à la place.
:::
%pip install -r /Workspace/shared/prod_requirements.txt
Consultez Format de fichier des exigences pour plus d'information sur les fichiers requirements.txt.
Recommandations concernant la taille des nœuds Driver
L'utilisation de bibliothèques limitées aux notebooks peut entraîner davantage de trafic vers le nœud du driver, car il s'efforce de maintenir un environnement cohérent entre les nœuds d'exécuteur.
Lorsque vous utilisez un cluster avec 10 nœuds ou plus, Databricks recommande ces spécifications comme exigence minimale pour le nœud Driver :
- Pour un cluster CPU de 100 nœuds, utilisez r6id.8xlarge pour x86 et r7gd.8xlarge pour ARM.
- Pour un cluster GPU de 10 nœuds, utilisez p2.xlarge.
Pour les clusters plus grands, utilisez un nœud Driver plus grand.
Différences entre %pip, %sh pip et !pip
%sh et ! exécute une commande shell dans un notebook ; le premier est une commande magique auxiliaire Databricks, tandis que le second est une fonctionnalité d'IPython. pip est un raccourci pour %pip lorsque l'automagic est activé, ce qui est le default dans les Notebooks Python de Databricks.
Sur Databricks Runtime 11.3 LTS et versions supérieures, %pip, %sh pip et !pip installent tous une bibliothèque en tant que bibliothèque Python limitée au notebook. Sur Databricks Runtime 10.4 LTS et versions antérieures, Databricks recommande d'utiliser uniquement %pip ou pip pour installer les bibliothèques propres aux Notebooks. 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 à l'échelle du Notebook sont incompatibles avec les Jobs de streaming par batch. Databricks recommande d'utiliser les bibliothèques de clusters ou le noyau IPython à la place.