Bibliotecas Python com escopo no notebook

As bibliotecas no escopo do notebook permitem criar, modificar, salvar, reutilizar e compartilhar ambientes personalizados do Python específicos de um notebook. Quando você instala uma biblioteca com escopo de notebook, somente o notebook atual e os trabalhos associados a esse notebook têm acesso a essa biblioteca. Outros notebooks anexados ao mesmo cluster não são afetados.

As bibliotecas no escopo do notebook não persistem entre sessões. Você deve reinstalar bibliotecas no escopo do notebook no início de cada sessão, ou sempre que o notebook for desvinculado de um cluster.

A Databricks recomenda usar o comando mágico %pip para instalar bibliotecas do Python no escopo do notebook. Em notebooks sem servidor que executam o ambiente versão 5 ou superior, você também pode usar %uv pip para instalações mais rápidas.

Você pode usar %pip em notebooks agendados como tarefas. Se você precisar gerenciar o ambiente do Python em um notebook Scala, SQL ou R, use o comando magic %python em combinação com %pip.

Você pode ter um aumento no tráfego no nó do driver ao trabalhar com instalações de bibliotecas no escopo do notebook. Consulte as recomendações de tamanho do nó do driver.

Para instalar bibliotecas para todos os notebooks vinculados a um cluster, use as bibliotecas do cluster. Consulte bibliotecas com escopo de computação.

Para obter uma visão geral abrangente das opções disponíveis para instalar bibliotecas do Python no Databricks, consulte Gerenciamento de ambiente do Python.

Gerenciar bibliotecas com comandos%pip

O comando %pip é equivalente ao comando pip e dá suporte à mesma API. As seções a seguir mostram exemplos de como você pode usar comandos %pip para gerenciar seu ambiente. Para obter mais informações sobre como instalar pacotes do Python com pip, consulte a Documentação de instalação do pip e as páginas relacionadas.

Importante

• %pip comandos não reiniciam automaticamente o processo de Python. Se você instalar um novo pacote ou atualizar um pacote existente, talvez seja necessário usar dbutils.library.restartPython() para ver os novos pacotes. Confira Reiniciar o processo do Python no Azure Databricks.
• Atualizar, modificar ou desinstalar pacotes principais do Python (como o IPython) com %pip pode fazer com que algumas funcionalidades parem de funcionar conforme o esperado. Se você tiver esses problemas, redefina o ambiente reiniciando o cluster ou iniciando uma nova sessão.

Instalações mais rápidas com %uv pip

Observação

%uv pip só está disponível em notebooks sem servidor executando o ambiente versão 5 ou superior. Não há suporte %uv pippara versões de computação clássicas e de ambiente sem servidor anteriores.

O %uv pip comando mágico é uma alternativa mais rápida para %pip. %uv pip é alimentado pelo gerenciador de pacotes uv e compartilha o mesmo ambiente virtual de notebook que %pip, portanto, os pacotes instalados com uma ferramenta são visíveis para o outro.

%uv pip é mais rápido do que %pip para instalações e operações somente leitura, como list. Isso o torna adequado para iteração sobre uma especificação de ambiente.

%uv pip suporta os subcomandos padrão pip: install, uninstall, list, show, freeze, check e tree.

%uv pip install simplejson

%uv pip list

Outros padrões de instalação nesta página (volumes, arquivos de espaço de trabalho, arquivos de requisitos, controle de versão, repositórios privados) funcionam com %uv pip. Você pode substituir %pip em %uv pip qualquer um desses exemplos.

%uv pip Limitações

• %uv pip uninstall não é possível remover totalmente as bibliotecas pré-instaladas no ambiente sem servidor. Somente os metadados do pacote são removidos. Os arquivos subjacentes permanecem no sistema de arquivos e o pacote ainda é importável.
• %uv pip não verifica se há conflitos de dependência em relação a bibliotecas pré-instaladas.
• Depois de executar os comandos %uv pip, o painel lateral Environment do notebook pode exibir algumas bibliotecas pré-instaladas como instaladas pelo usuário. Esse é um problema de exibição e não afeta a funcionalidade do pacote.
• %uv pip destina-se à iteração interativa rápida. Para configurar um ambiente reproduzível para o notebook, adicione dependências no painel lateral ambiente do notebook.

Instalar uma biblioteca com %pip

%pip install matplotlib

Instalar um pacote wheel do Python com %pip

%pip install /path/to/my_package.whl

Desinstalar uma biblioteca com %pip

Observação

Não é possível desinstalar uma biblioteca incluída nas notas da versão e compatibilidade do Databricks Runtime nem uma biblioteca instalada como biblioteca do cluster. Se você tiver instalado uma versão de biblioteca diferente da versão incluída no Databricks Runtime ou da instalada no cluster, poderá usar %pip uninstall para reverter a biblioteca para a versão padrão no Databricks Runtime ou para a versão instalada no cluster, mas não poderá usar um comando %pip para desinstalar a versão de uma biblioteca incluída no Databricks Runtime ou instalada no cluster.

%pip uninstall -y matplotlib

A opção -y é obrigatória.

Instalar uma biblioteca de um sistema de controle de versão com %pip

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

Você pode adicionar parâmetros à URL para especificar parâmetros como a versão ou o subdiretório git. Consulte o Suporte do VCS para obter mais informações e exemplos que usem outros sistemas de controle de versão.

Instalar um pacote privado com credenciais gerenciadas pelos segredos do Databricks com %pip

O pip dá suporte à instalação de pacotes de fontes privadas com autenticação básica, incluindo sistemas de controle de versão privados e repositórios de pacotes privados, como Nexus e Artifactory. O gerenciamento de segredos está disponível por meio da API de Segredos do Databricks, que permite armazenar tokens de autenticação e senhas. Use a API DBUtils para acessar segredos do notebook. Observe que você pode usar $variables em comandos mágicos.

Para instalar um pacote de um repositório privado, especifique a URL do repositório com a opção --index-url para %pip install ou adicione-a ao arquivo de configuração pip em ~/.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/

Da mesma forma, você pode usar o gerenciamento de segredos com comandos mágicos para instalar pacotes privados a partir de sistemas de controle de versão.

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

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

Instalar um pacote do DBFS com %pip

Importante

Qualquer usuário do workspace pode modificar arquivos armazenados no DBFS. O Azure Databricks recomenda armazenar arquivos em workspaces ou em volumes do Catálogo do Unity.

Você pode usar %pip para instalar um pacote privado que foi salvo no DBFS.

Quando você carrega um arquivo no DBFS, ele renomeia automaticamente o arquivo, substituindo espaços, pontos e hifens por sublinhados. Para arquivos wheel do Python, pip exige que o nome do arquivo use pontos na versão (por exemplo, 0.1.0) e hifens em vez de espaços ou sublinhados; portanto, esses nomes de arquivo não são alterados.

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

Instalar um pacote de um volume com %pip

Importante

Esse recurso está em uma versão prévia.

Com o Databricks Runtime 13.3 LTS e superior, você pode usar %pip para instalar um pacote privado que foi salvo em um volume.

Quando você carrega um arquivo em um volume, ele automaticamente renomeia o arquivo, substituindo espaços, pontos e hifens por sublinhados. Para arquivos wheel do Python, pip exige que o nome do arquivo use pontos na versão (por exemplo, 0.1.0) e hifens em vez de espaços ou sublinhados; por isso, esses nomes de arquivo não são alterados.

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

Instalar um pacote armazenado como um arquivo de workspace com %pip

Com o Databricks Runtime 11.3 LTS e versões superiores, você pode usar %pip para instalar um pacote privado que foi salvo como um arquivo do espaço de trabalho.

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

Salvar bibliotecas em um arquivo de requisitos

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

Todos os subdiretórios no caminho do arquivo já devem existir. Se você executar %pip freeze > /Workspace/<new-directory>/requirements.txt, o comando falhará se o diretório /Workspace/<new-directory> ainda não existir.

Usar um arquivo de requisitos para instalar bibliotecas

Um arquivo de requisitos contém uma lista de pacotes a serem instalados usando pip. Um exemplo de como usar um arquivo de requisitos é:

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

Consulte Formato de arquivo de requisitos para obter mais informações sobre arquivos requirements.txt.

Recomendações de tamanho do nó do driver

O uso de bibliotecas com escopo de notebook pode resultar em mais tráfego para o nó do driver, já que ele trabalha para manter o ambiente consistente em todos os nós executores.

Quando você usa um cluster com 10 ou mais nós, a Databricks recomenda as seguintes especificações como requisito mínimo para o nó de driver:

• Para um cluster de CPU de 100 nós, use Standard_D8ds_v5.
• Para um cluster de GPU de 10 nós, use Standard_NC12.

Para clusters maiores, use um nó de driver maior.

Diferenças entre %pip, %sh pipe !pip

%sh e ! executam um comando de shell em um notebook; o primeiro é um comando mágico auxiliar do Databricks, e o segundo é um recurso do IPython. pip é uma abreviação de %pip quando o automagic está habilitado, que é o padrão em notebooks Python do Azure Databricks.

No Databricks Runtime 11.3 LTS e versões posteriores, %pip, %sh pip e !pip instalam uma biblioteca como biblioteca Python com escopo no notebook. No Databricks Runtime 10.4 LTS e versões inferiores, o Databricks recomenda usar apenas %pip ou pip para instalar bibliotecas com escopo de notebook. O comportamento de %sh pip e !pip não é consistente no Databricks Runtime 10.4 LTS e versões inferiores.

Problemas conhecidos

• No Databricks Runtime 9.1 LTS, as bibliotecas com escopo de notebook são incompatíveis com trabalhos de streaming em lote. O Databricks recomenda usar bibliotecas de cluster ou o kernel do IPython.