Bibliotecas Python ao nível do notebook

As bibliotecas com âmbito de notebook permitem criar, modificar, guardar, reutilizar e partilhar ambientes Python personalizados específicos de um notebook. Quando instala uma biblioteca ao nível do notebook, apenas o notebook atual e quaisquer tarefas associadas a esse notebook têm acesso a essa biblioteca. Outros blocos de notas associados ao mesmo cluster não são afetados.

As bibliotecas ao nível do notebook não persistem entre sessões. Você deve reinstalar bibliotecas com escopo de bloco de anotações no início de cada sessão ou sempre que o bloco de anotações for desanexado de um cluster.

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

Você pode usar %pip em blocos de anotações agendados como trabalhos. Se precisar de gerir o ambiente do Python num notebook de Scala, SQL ou R, utilize o comando mágico %python em conjunto com %pip.

Poderá verificar-se mais tráfego no nó do controlador ao trabalhar com instalações de bibliotecas ao nível do notebook. Consulte as recomendações relativas ao tamanho do nó do controlador.

Para instalar bibliotecas para todos os notebooks associados a um cluster, utilize as bibliotecas do cluster. Consulte Bibliotecas abrangidas por computação.

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

Gerenciar bibliotecas com %pip comandos

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

Importante

• Os comandos %pip não reiniciam automaticamente o processo 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. Consulte Reiniciar o processo Python no Azure Databricks.
• Atualizar, modificar ou desinstalar pacotes principais do Python (como o IPython) com %pip pode fazer com que algumas funcionalidades deixem 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

Nota

%uv pip só está disponível em notebooks sem servidor com a versão 5 do ambiente ou superior. O Classic Compute e as versões anteriores do ambiente serverless não suportam %uv pip.

O %uv pip comando mágico é uma alternativa mais rápida a %pip. %uv pip é alimentado pelo gestor de pacotes UV e partilha o mesmo ambiente virtual de portátil que %pip, pelo que os pacotes instalados com uma ferramenta são visíveis para a outra.

%uv pip é mais rápido do que %pip para instalações e operações de apenas leitura como list. Isto torna-o particularmente adequado para iterar com base numa especificação do 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, ficheiros de espaço de trabalho, ficheiros de requisitos, controlo de versões, repositórios privados) funcionam com %uv pip. Podes substituir %pip por %uv pip em qualquer um destes exemplos.

%uv pip Limitações

• %uv pip uninstall Não é possível remover completamente bibliotecas que estejam pré-instaladas no ambiente serverless. Apenas os metadados do pacote são removidos. Os ficheiros subjacentes permanecem no sistema de ficheiros e o pacote continua importável.
• %uv pip não verifica conflitos de dependências em bibliotecas pré-instaladas.
• Após executar os comandos %uv pip, o painel lateral Ambiente do notebook pode apresentar algumas bibliotecas pré-instaladas como se tivessem sido instaladas pelo utilizador. Isto é um problema de visualização e não afeta a funcionalidade do pacote.
• %uv pip destina-se a iterações rápidas e interativas. Para configurar um ambiente reproduzível para o bloco de notas, adicione dependências no painel lateral Ambiente do bloco de notas.

Instale uma biblioteca com %pip

%pip install matplotlib

Instale um pacote de roda Python com %pip

%pip install /path/to/my_package.whl

Desinstalar uma biblioteca com %pip

Nota

Não é possível desinstalar uma biblioteca incluída nas versões e compatibilidade das notas de versão do Databricks Runtime ou uma biblioteca que tenha sido instalada como uma biblioteca de cluster. Se você tiver instalado uma versão de biblioteca diferente da incluída no Databricks Runtime ou da instalada no cluster, poderá reverter %pip uninstall 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 %pip comando para desinstalar a versão de uma biblioteca incluída no Databricks Runtime ou instalada no cluster.

%pip uninstall -y matplotlib

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

Instale uma biblioteca a partir 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 coisas como a versão ou o subdiretório git. Consulte o suporte VCS para obter mais informações e exemplos de utilização de outros sistemas de controlo de versão.

Instale um pacote privado com credenciais geridas pelos segredos do Databricks com %pip

pip suporta a 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 Databricks Secrets, que permite armazenar tokens de autenticação e senhas. Utilize a API DBUtils para aceder aos segredos do seu notebook. Note que você pode usar $variables em comandos mágicos.

Para instalar um pacote de um repositório privado, especifique o URL do repositório com a opção --index-url de %pip install ou adicione-o ao ficheiro 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 secreto com comandos mágicos para instalar pacotes privados 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>

Instale um pacote do DBFS com %pip

Importante

Qualquer usuário do espaço de trabalho pode modificar arquivos armazenados no DBFS. O Azure Databricks recomenda armazenar arquivos em espaços de trabalho ou em volumes do Catálogo 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 hífenes por sublinhados. Para arquivos de roda Python, pip requer que o nome do arquivo use períodos na versão (por exemplo, 0.1.0) e hífenes em vez de espaços ou sublinhados, para que esses nomes de arquivos não sejam alterados.

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

Instale um pacote a partir de um volume com %pip

Importante

Esta funcionalidade está em Pré-visualização Pública.

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 renomeia automaticamente o arquivo, substituindo espaços, pontos e hífenes por sublinhados. Para arquivos de roda Python, pip requer que o nome do arquivo use períodos na versão (por exemplo, 0.1.0) e hífenes em vez de espaços ou sublinhados, para que esses nomes de arquivos não sejam alterados.

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

Instale um pacote armazenado como um ficheiro de área de trabalho com %pip

Com o Databricks Runtime 11.3 LTS e superior, você pode usar %pip para instalar um pacote privado que foi salvo como um arquivo de 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> não existir ainda.

Usar um arquivo de requisitos para instalar bibliotecas

Um arquivo de requisitos contém uma lista de pacotes a serem instalados usando pipo . Um exemplo de uso de um arquivo de requisitos é:

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

Consulte Formato do ficheiro de requisitos para obter mais informações sobre os ficheiros requirements.txt.

Recomendações relativas à dimensão do nó controlador

A utilização de bibliotecas com âmbito do notebook pode resultar em maior tráfego para o nó do controlador, ao procurar manter o ambiente consistente pelos nós executores.

Quando utiliza um cluster com 10 ou mais nós, a Databricks recomenda as seguintes especificações como requisito mínimo para o nó do 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, utilize um nó do controlador maior.

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

%sh e ! executam um comando de shell num notebook; o primeiro deles é um comando mágico auxiliar do Databricks, enquanto o segundo é uma funcionalidade do IPython. pip é uma abreviação para %pip quando o automagic está habilitado, que é o padrão nos blocos de anotações Python do Azure Databricks.

No Databricks Runtime 11.3 LTS e superior, %pip, %sh pipe !pip todos instalam uma biblioteca como uma biblioteca Python com escopo de notebook. Na Databricks Runtime 10.4 LTS e versões inferiores, a Databricks recomenda utilizar apenas %pip ou pip para instalar bibliotecas com âmbito de notebook. O comportamento de %sh pip e !pip não é consistente no Databricks Runtime 10.4 LTS e inferior.

Problemas conhecidos

• No Databricks Runtime 9.1 LTS, as bibliotecas com âmbito de notebook são incompatíveis com tarefas de streaming em lote. Databricks recomenda a utilização de bibliotecas do cluster ou do kernel IPython em vez disso.