Bibliotecas de Python cuyo ámbito es el cuaderno

Las bibliotecas con ámbito de cuaderno permiten crear, modificar, guardar, reutilizar y compartir entornos de Python personalizados específicos de un cuaderno. Al instalar una biblioteca de ámbito de cuaderno, solo el cuaderno actual y los trabajos asociados a él tienen acceso a la biblioteca en cuestión. Los otros cuadernos asociados al mismo clúster no se ven afectados.

Las bibliotecas con ámbito de cuaderno no se conservan entre sesiones. Debe volver a instalar las bibliotecas con ámbito de cuaderno al principio de cada sesión o siempre que el cuaderno se desasocie de un clúster.

Databricks recomienda usar el comando magic %pip para instalar bibliotecas de Python con ámbito de cuaderno.

Puede usar %pip en cuadernos programados como trabajos. Si necesita administrar el entorno de Python en un cuaderno de Scala, SQL o R, use el comando magic %python junto con %pip.

Es posible que experimente más tráfico en el nodo de controlador al trabajar con instalaciones de biblioteca con ámbito de cuaderno. Consulte ¿Qué tamaño debe tener el nodo de controlador al trabajar con bibliotecas con ámbito de cuaderno?.

Para instalar bibliotecas para todos los cuadernos asociados a un clúster, use bibliotecas de clúster. Consulte Bibliotecas del clúster.

Para obtener información general completa sobre las opciones disponibles para instalar bibliotecas de Python en Databricks, consulte Administración del entorno de Python.

Nota:

En Databricks Runtime 10.4 LTS y versiones anteriores, puede usar la utilidad de biblioteca de Azure Databricks (heredada). La utilidad de biblioteca solo se admite en Databricks Runtime, no en Databricks Runtime ML. Consulte Utilidad de biblioteca (dbutils.library) (heredado).

Administración de bibliotecas con comandos de %pip

El comando %pip es equivalente a pip y admite la misma API. En las secciones siguientes se muestran ejemplos de cómo puede usar comandos %pip para administrar el entorno. Para obtener más información sobre cómo instalar paquetes de Python con pip, consulte la documentación sobre la instalación de pip y sus páginas relacionadas.

Importante

• A partir de Databricks Runtime 13.0 %pip, los comandos no reinician automáticamente el proceso de Python. Si instala un nuevo paquete o actualiza un paquete existente, es posible que tenga que usar dbutils.library.restartPython() para ver los nuevos paquetes. Consulte Reinicio del proceso de Python en Azure Databricks.
• En Databricks Runtime 12.2 LTS y versiones posteriores, Databricks recomienda colocar todos los comandos %pip al principio del cuaderno. El estado del cuaderno se restablece después de cualquier comando %pip que modifique el entorno. Si crea métodos o variables de Python en un cuaderno y, después, usa comandos %pip en una celda posterior, se pierden los métodos o variables.
• La actualización, modificación o desinstalación de paquetes principales de Python (como IPython) con %pip puede hacer que algunas características dejen de funcionar según lo previsto. Si experimenta estos problemas, restablezca el entorno desasociando y asociando otra vez el cuaderno, o bien reiniciando el clúster.

Instalación de una biblioteca con %pip

%pip install matplotlib

Instalación de un paquete wheel de Python con %pip

%pip install /path/to/my_package.whl

Desinstalación de una biblioteca con %pip

Nota:

No se puede desinstalar una biblioteca incluida en las versiones de las notas de la versión y compatibilidad de Databricks Runtime o una biblioteca que se haya instalado como una biblioteca de clúster. Si ha instalado una versión de biblioteca diferente de la incluida en Databricks Runtime o la instalada en el clúster, puede usar %pip uninstall para revertir la biblioteca a la versión predeterminada de Databricks Runtime o la versión instalada en el clúster, pero no puede usar un comando %pip para desinstalar la versión de una biblioteca incluida en Databricks Runtime o instalada en el clúster.

%pip uninstall -y matplotlib

La opción -y es obligatoria.

Instalación de una biblioteca desde un sistema de control de versiones con %pip

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

Puede agregar parámetros a la dirección URL para especificar información como la versión o el subdirectorio de Git. Consulte la compatibilidad con sistemas de control de versiones para obtener más información y ejemplos de uso de otros sistemas de control de versiones.

Instalación de un paquete privado con credenciales administradas por secretos de Databricks con %pip

Pip admite la instalación de paquetes desde orígenes privados con autenticación básica, incluidos los sistemas de control de versiones privados y los repositorios de paquetes privados, como Nexus y Artifactory. La administración de secretos está disponible mediante la API de secretos de Databricks, que permite almacenar tokens de autenticación y contraseñas. Use la API de DBUtils para acceder a los secretos desde el cuaderno. Tenga en cuenta que puede usar $variables en comandos magic.

Para instalar un paquete desde un repositorio privado, especifique la dirección URL del repositorio con la opción --index-url a %pip install o agréguelo al archivo de configuración pip en ~/.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 forma similar, puede usar la administración de secretos con comandos magic para instalar paquetes privados desde sistemas de control de versiones.

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

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

Instalación de un paquete desde DBFS con %pip

Importante

Cualquier usuario del área de trabajo puede modificar los archivos almacenados en DBFS. Azure Databricks recomienda almacenar archivos en áreas de trabajo o en volúmenes de Unity Catalog.

Puede usar %pip para instalar un paquete privado que se haya guardado en DBFS.

Al cargar un archivo en DBFS, este cambia automáticamente el nombre del archivo, reemplazando espacios, puntos y guiones por caracteres de subrayado. En el caso de los archivos Wheel de Python, pip necesita que se usen puntos para la versión en el nombre del archivo (por ejemplo, 0.1.0) y guiones en lugar de espacios o guiones bajos, por lo que estos nombres de archivo no se modifican.

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

Instalación de un paquete desde un volumen con %pip

Importante

Esta característica está en versión preliminar pública.

Con Databricks Runtime 13.3 LTS y versiones posteriores, puede usar %pip para instalar un paquete privado que se ha guardado en un volumen.

Al cargar un archivo en un volumen, este cambia automáticamente el nombre del archivo, reemplazando espacios, puntos y guiones por caracteres de subrayado. En el caso de los archivos Wheel de Python, pip necesita que se usen puntos para la versión en el nombre del archivo (por ejemplo, 0.1.0) y guiones en lugar de espacios o guiones bajos, por lo que estos nombres de archivo no se modifican.

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

Instalar un paquete almacenado como un archivo del área de trabajo con %pip

Con Databricks Runtime 11.3 LTS y versiones posteriores, puede usar %pip para instalar un paquete privado que se ha guardado como un archivo del área de trabajo.

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

Guardado de bibliotecas en un archivo de requisitos

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

Los subdirectorios de la ruta de acceso del archivo deben haberse creado anteriormente. Si ejecuta %pip freeze > /Workspace/<new-directory>/requirements.txt, se produce un error en el comando en el caso de que el directorio /Workspace/<new-directory> aún no exista.

Uso de un archivo de requisitos para instalar bibliotecas

Un archivo de requisitos contiene una lista de paquetes que se instalarán mediante pip. Un ejemplo de uso de un archivo de requisitos es el siguiente:

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

Consulte Formato de un archivo de requisitos para obtener más información sobre los archivos requirements.txt.

¿Qué tamaño debe tener el nodo de controlador al trabajar con bibliotecas con ámbito de cuaderno?

El uso de bibliotecas con ámbito de cuaderno podría dar lugar a más tráfico hacia el nodo de controlador, ya que funciona para mantener la coherencia del entorno entre los nodos ejecutores.

Cuando se usa un clúster con 10 nodos o más, Databricks recomienda estas especificaciones como requisito mínimo para el nodo de controlador:

• Para un clúster de CPU de 100 nodos, use Standard_DS5_v2.
• Para un clúster de GPU de 10 nodos, use Standard_NC12.

Para clústeres más grandes, use un nodo de controlador mayor.

¿Puedo usar %sh pip, !pip o pip? ¿Cuál es la diferencia?

%shy ! ejecutan un comando de shell en un cuaderno; el primero es un comando mágico auxiliar de Databricks, mientras que este último es una característica de IPython. pip es una abreviatura de %pip cuando se habilita automagic, que es el valor predeterminado en cuadernos de Python de Azure Databricks.

En Databricks Runtime 11.3 LTS y versiones posteriores, %pip, %sh pipy !pip instalan una biblioteca como una biblioteca de Python con ámbito de cuaderno. En Databricks Runtime 10.4 LTS y versiones posteriores, Databricks recomienda usar solo %pip o pip instalar bibliotecas con ámbito de cuaderno. El comportamiento de %sh pip y !pip no es coherente en Databricks Runtime 10.4 LTS y versiones posteriores.

Problemas conocidos

• En Databricks Runtime 9.1 LTS, las bibliotecas con ámbito de cuaderno no son compatibles con los trabajos de streaming por lotes. Databricks recomienda usar bibliotecas de clúster o el kernel de IPython en su lugar.