Notebook-scoped Python biblioteca
As bibliotecas com escopo para notebooks permitem que você crie, modifique, salve, reutilize e compartilhe ambientes Python personalizados que são específicos de um notebook. Quando você instala uma biblioteca com escopo para notebooks, somente o notebook atual e quaisquer jobs associados a esse notebook têm acesso a essa biblioteca. Outros notebooks conectados ao mesmo cluster não são afetados.
As bibliotecas com escopo para notebooks não persistem entre as sessões. O senhor deve reinstalar as bibliotecas com escopo para notebooks no início de cada sessão ou sempre que o notebook for desconectado de um cluster.
O Databricks recomenda o uso do comando mágico %pip para instalar bibliotecas Python com escopo de notebook. Em notebooks serverless executando a versão de ambiente 5 ou superior, você também pode usar comandos%uv para gerenciar projetos e pacotes Python.
O senhor pode usar o site %pip no Notebook agendado como Job. Se precisar gerenciar o ambiente Python em um Scala, SQL ou R Notebook, use o comando mágico %python em conjunto com %pip.
Você poderá observar um aumento no tráfego para o nó do driver ao trabalhar com instalações de biblioteca com escopo de Notebook. Consulte as recomendações de tamanho do nó do driver.
Para instalar o biblioteca para todos os Notebooks anexados a um cluster, use o biblioteca de cluster. Consulte biblioteca com escopo de computação.
Para obter uma visão geral abrangente das opções disponíveis para a instalação da Python biblioteca em Databricks, consulte Python environment management.
gerenciar biblioteca com %uv comando
O comando mágico %uv usa o uv, um gerenciador de pacotes e projetos Python. Você pode usar os comandos de projeto %uv para gerenciar um ambiente de projeto ou os comandos %uv pip para gerenciar bibliotecas com escopo de notebook.
Criar ambientes de projeto reproduzíveis com %uv
%uv comandos de projeto exigem um notebook Serverless executando a versão de ambiente 5 ou acima.
Use os comandos de projeto %uv para gerenciar dependências e sincronizar o ambiente do projeto de forma reprodutível. O Databricks suporta apenas os seguintes comandos de projeto:
Comando | Descrição |
|---|---|
| Gerar |
| Adicione uma dependência a |
| Remova uma dependência de |
| Atualize o ambiente do projeto para corresponder às dependências em |
| Gere ou atualize |
| Exiba a árvore de dependências do projeto. |
| Exporte o lockfile do projeto para outro formato, como |
Ao usar o Compartilhado Serverless, o Databricks reconhece o arquivo pyproject.toml na pasta Git ou na raiz do pacote. Este arquivo configura o ambiente compartilhado para notebooks e arquivos anexados ao mesmo recurso de compute.
Por exemplo, o seguinte pyproject.toml especifica a dependência simplejson e a versão 5 do ambiente serverless:
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
"simplejson==3.18.1",
]
[tool.databricks.environment]
environment_version = "5"
Depois de editar pyproject.toml, execução %uv sync em um notebook anexado para aplicar as alterações ao ambiente compartilhado. No editor de pasta ou bundle Git, você também pode clicar em Aplicar na parte superior do editor de arquivos pyproject.toml. Consulte Editar pyproject.toml para Serverless Compartilhado.
Para mais informações, consulte a documentação do uv para trabalhar em projetos e a referência de comandos do uv.
Instalações mais rápidas com %uv pip
%uv pip Está disponível apenas em notebooks serverless executando o ambiente versão 5 ou superior. O ambiente clássico compute e versões anteriores do ambiente serverless não suportam %uv pip.
O comando mágico %uv pip é uma alternativa mais rápida ao %pip. %uv pip é alimentado pelo gerenciador de pacotes uv e compartilha o mesmo ambiente virtual Notebook que %pip, portanto, os pacotes instalados com uma ferramenta são visíveis para a outra.
%uv pip é mais rápido que %pip para instalações e operações somente leitura, como list. Isso o torna bastante adequado para iteração em cima de 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 workspace , arquivos de requisitos, controle de versão, repositórios privados) funcionam com %uv pip. Você pode substituir %pip por %uv pip em qualquer um desses exemplos.
%uv pip limitações
%uv pip uninstallNão é possível remover completamente as bibliotecas pré-instaladas no ambiente serverless . Apenas os metadados do pacote são removidos. Os arquivos subjacentes permanecem no sistema de arquivos e o pacote ainda pode ser importado.%uv pipNão verifica conflitos de dependência com a biblioteca pré-instalada.- Após executar o comando
%uv pip, o painel lateral Ambiente do Notebook pode exibir algumas bibliotecas pré-instaladas como instaladas pelo usuário. Trata-se de um problema de exibição e não afeta a funcionalidade do pacote. %uv pipÉ projetado para iteração interativa rápida. Para configurar um ambiente reproduzível para o Notebook, adicione as dependências no painel lateral Ambiente do Notebook.
gerenciar biblioteca com %pip comando
O comando %pip é equivalente ao comando pip e suporta a mesma API. As seções a seguir mostram exemplos de como o senhor pode usar o %pip comando para gerenciar seu ambiente. Para obter mais informações sobre a instalação do Python pacote com pip, consulte a documentação do pip install e as páginas relacionadas.
%pipO comando não reinicia automaticamente o processo Python . Se você instalar um novo pacote ou atualizar um pacote existente, talvez precise usardbutils.library.restartPython()para ver o novo pacote. Consulte Reiniciar o processo do Python no Databricks.- Atualizar, modificar ou desinstalar o pacote Python principal (como o IPython) com
%pippode fazer com que alguns recursos parem de funcionar conforme o esperado. Se o senhor tiver esses problemas, redefina o ambiente reiniciando o clustering ou iniciando uma nova sessão.
Instale uma biblioteca com %pip
%pip install matplotlib==3.8.4
Instale um pacote Python wheel com %pip
%pip install /path/to/my_package.whl
Desinstale uma biblioteca com %pip
O senhor não pode desinstalar uma biblioteca que esteja incluída em Databricks Runtime notas sobre versões e compatibilidade ou uma biblioteca que tenha sido instalada como uma biblioteca de clustering. Se o senhor tiver instalado uma versão de biblioteca diferente da incluída em Databricks Runtime ou da instalada no clustering, poderá usar %pip uninstall para reverter a biblioteca para a versão default em Databricks Runtime ou para a versão instalada no clustering, mas não poderá usar um comando %pip para desinstalar a versão de uma biblioteca incluída em Databricks Runtime ou instalada no clustering.
%pip uninstall -y matplotlib
A opção -y é obrigatória.
Instale 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 ao URL para especificar coisas como a versão ou o subdiretório git. Consulte o suporte do VCS para obter mais informações e exemplos de uso de outros sistemas de controle de versão.
Instale um pacote privado com credenciais gerenciadas por Databricks secrets com %pip
O pip oferece suporte à instalação do pacote a partir de fontes privadas com autenticação básica, incluindo sistemas privados de controle de versão e repositórios privados do pacote, como Nexus e Artifactory. O gerenciamento de segredos está disponível por meio da API Databricks Secrets, que permite que o senhor armazene tokens e senhas de autenticação. Use o DBUtils API para acessar os segredos do seu Notebook. Observe que o senhor pode usar $variables no comando mágico.
Para instalar um pacote de um repositório privado, especifique o URL do repositório com a opção --index-url em %pip install ou adicione-o 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/
De forma semelhante, é possível utilizar o gerenciamento de segredos 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
Qualquer usuário do site workspace pode modificar os arquivos armazenados no site DBFS. Databricks recomenda o armazenamento de arquivos no espaço de trabalho ou em volumes Unity Catalog.
Você pode utilizar o %pip para instalar um pacote privado que foi salvo no DBFS.
Quando o senhor upload um arquivo para DBFS, ele renomeia automaticamente o arquivo, substituindo espaços, pontos e hífens por sublinhado. Para arquivos Python wheel, pip exige que o nome do arquivo use pontos na versão (por exemplo, 0.1.0) e hífens em vez de espaços ou sublinhado, portanto, esses nomes de arquivos não são alterados.
%pip install /Volumes/<catalog>/<schema>/<volume>/mypackage-0.0.1-py3-none-any.whl
Instalar um pacote de um volume com %pip
Visualização
Esse recurso está em Public Preview.
Com o Databricks Runtime 13.3 LTS e o acima, o senhor pode usar %pip para instalar um pacote privado que tenha sido salvo em um volume.
Quando o senhor upload um arquivo em um volume, ele renomeia automaticamente o arquivo, substituindo espaços, pontos e hífens por sublinhado. Para arquivos Python wheel, pip exige que o nome do arquivo use pontos na versão (por exemplo, 0.1.0) e hífens em vez de espaços ou sublinhado, portanto, esses nomes de arquivos não são alterados.
%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl
Instale um pacote armazenado como um arquivo workspace com %pip
Com Databricks Runtime 11.3 LTS e acima, o senhor pode usar %pip para instalar um pacote privado que tenha sido salvo como um arquivo workspace.
%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl
Salvar a biblioteca em um arquivo de requisitos
%pip freeze > /Workspace/shared/prod_requirements.txt
Quaisquer subdiretórios no caminho do arquivo já devem existir. Se você executar o %pip freeze > /Workspace/<new-directory>/requirements.txt, o comando falhará se o diretório /Workspace/<new-directory> ainda não existir.
Use um arquivo de requisitos para instalar o biblioteca
Um arquivo de requisitos contém uma lista do pacote a ser instalado usando pip. Um exemplo de uso de um arquivo de requisitos é:
Recomendamos descontinuar o uso de comandos %pip install não fixados, já que eles não são compatíveis com a arquitetura de compute serverless do Databricks. Utilize pin to ==<version> em vez disso.
%pip install -r /Workspace/shared/prod_requirements.txt
Consulte Requirements File Format para obter mais informações sobre os arquivos requirements.txt.
Recomendações de tamanho do nó do driver
O uso de bibliotecas com escopo para notebooks pode resultar em mais tráfego para o nó do driver, à medida que ele trabalha para manter o ambiente consistente em todos os nós de execução.
Quando o senhor usa um clustering com 100 ou mais nós, o requisito mínimo para o nó do driver é o tipo de instância c3-standard-22-lssd.
Para clusters maiores, use um nó de driver maior.
Diferenças entre %pip, %sh pip e !pip
%sh e ! executam um shell comando em um Notebook; o primeiro é um Databricks comando mágico auxiliar e o último é um recurso do IPython. pip é uma abreviação de %pip quando a automagia está ativada, que é o default em Databricks Python Notebook.
Em Databricks Runtime 11.3 LTS e acima, %pip, %sh pip e !pip instalam uma biblioteca como uma Python biblioteca com escopo de Notebook. Em Databricks Runtime 10.4 LTS e abaixo, Databricks recomenda usar apenas %pip ou pip para instalar a biblioteca com escopo de Notebook. O comportamento de %sh pip e !pip não é consistente no Databricks Runtime 10.4 LTS e abaixo.
Problemas conhecidos
- No site Databricks Runtime 9.1 LTS, a biblioteca com escopo de notebook é incompatível com o trabalho de transmissão de lotes. Databricks recomenda usar a biblioteca de clustering ou o kernel IPython.