Esta página foi traduzida pela API Cloud Translation.

Especificar dependências no Python

Especifique as dependências do aplicativo para versões compatíveis do Python usando uma destas abordagens:

Use um arquivo requirements.txt no diretório raiz. O arquivo precisa estar no mesmo diretório que o arquivo main.py que contém o código-fonte. O arquivo requirements.txt contém uma linha por pacote. Cada linha contém o nome do pacote e, como opção, a versão solicitada. Para evitar que seu build seja afetado por mudanças na versão de dependência, fixe os pacotes de dependência em uma versão específica.

A seguir, um exemplo de arquivo requirements.txt:
```
functions-framework
requests==2.20.0
numpy
```
Use um arquivo pyproject.toml para especificar dependências. Se você gerenciar as dependências do aplicativo em um arquivo pyproject.toml em vez do arquivo requirements.txt, o buildpack do Python vai determinar o gerenciador de pacotes com base na configuração especificada no arquivo pyproject.toml. Para mais informações, consulte Implantar aplicativos Python com um arquivo pyproject.toml.

Se o aplicativo usar os arquivos pyproject.toml e requirements.txt, o arquivo requirements.txt terá precedência.
- A seguir, um exemplo de arquivo pyproject.toml:
```
[project]
name = "demo-app"
version = "0.1.0"
description = ""
requires-python = ">=3.10"
dependencies = [
    "flask>=3.1.1",
    "gunicorn>=23.0.0",
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
```

Empacote dependências locais junto com sua função.

A especificação de dependência que usa o padrão Pipfile/Pipfile.lock não é compatível. Seu projeto não deve incluir esses arquivos.

Se você usar um arquivo requirements.txt para gerenciar dependências, o Cloud Run vai instalar o Functions Framework em seu nome ao criar uma função. No entanto, recomendamos que você inclua o Functions Framework como uma dependência explícita para evitar discrepâncias.

Ao usar um arquivo pyproject.toml, inclua o Functions Framework como uma dependência, porque o Cloud Run não o instala para você.

Gerenciador de pacotes

Se você gerenciar as dependências usando um requirements.txt file, o gerenciador de pacotes padrão vai variar de acordo com a versão do Python configurada.

Se você usar um arquivo pyproject.toml para gerenciar dependências em vez de um arquivo requirements.txt, o buildpack do Python vai determinar o gerenciador de pacotes com base nas configurações de configuração no arquivo pyproject.toml. O buildpack é compatível com os gerenciadores de pacotes pip, uv e Poetry. Para mais informações, consulte Implantar aplicativos Python com um arquivo pyproject.toml.

Python 3.14 e versões mais recentes

A partir da versão 3.14 do Python (pré-lançamento) e mais recentes, o pacote de build do Python usa o gerenciador de pacotes uv como o instalador padrão das dependências especificadas no arquivo requirements.txt.

Para usar o pip como gerenciador de pacotes, configure a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

Execute o comando gcloud run deploy para definir a variável de ambiente do gerenciador de pacotes como pip:

gcloud run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=pip

Substitua SERVICE pelo nome do serviço do Cloud Run.

Python 3.13 e versões anteriores

Para a versão 3.13 e anteriores do Python, o buildpack do Python usa o gerenciador de pacotes pip para instalar as dependências definidas no arquivo requirements.txt.

Para usar o uv (prévia) como gerenciador de pacotes, configure a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Execute o comando gcloud beta run deploy para definir a variável de ambiente do gerenciador de pacotes como uv:

gcloud beta run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=uv

Substitua SERVICE pelo nome do serviço do Cloud Run.

Empacotar dependências locais

Empacote e implante dependências junto com sua função. Essa abordagem é útil se a dependência não estiver disponível quando você usar um gerenciador de pacotes compatível ou se o acesso à Internet do ambiente do Cloud Run for restrito.

Também é possível usar um arquivo requirements.txt para especificar outras dependências que não tenham sido empacotadas junto com a função. Por exemplo, você pode usar a seguinte estrutura de diretórios:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

Importe o código de localpackage usando a seguinte instrução import:

# code in main.py
from localpackage import script

Essa abordagem não executa nenhum arquivo setup.py. É possível agrupar os pacotes com esses arquivos, mas eles podem não ser executados corretamente nas funções do Cloud Run.

Dependências copiadas

Dependências copiadas são aquelas em que a origem é incluída diretamente no pacote de código-fonte e recriada com seu próprio código. Use a variável de ambiente de build GOOGLE_VENDOR_PIP_DEPENDENCIES para criar dependências pip copiadas e evitar a instalação delas durante a implantação.

Criar dependências copiadas

Verifique se python3 está instalado no sistema de desenvolvimento.
Declare as dependências do aplicativo em um arquivo requirements.txt no diretório raiz da árvore de desenvolvimento.
Declare o Functions Framework como um requisito incluindo functions-framework em uma linha separada no arquivo requirements.txt.
Faça o download das dependências da função para o diretório local. As etapas para fazer isso dependem do tipo de arquivo de dependência: um arquivo wheel (*.whl) do Python ou um arquivo tar (*.tar.gz).
1. Se a dependência for um wheel do Python (*.whl), faça o download dela no diretório raiz da árvore de desenvolvimento com este comando pip:
```
python3 -m pip download -r requirements.txt --only-binary=:all: \
   -d DIRECTORY \
   --python-version PYTHON_RUNTIME_VERSION \
   --platform manylinux2014_x86_64 \
   --implementation cp
```
  Substitua:
  - DIRECTORY: o nome do diretório local para o download.
  - PYTHON_RUNTIME_VERSION: a versão do Python a ser usada para verificações de compatibilidade. Por exemplo, 314 para Python 3.14.
    Essa versão precisa corresponder a um dos ambientes de execução Python compatíveis.
  A estrutura de diretórios resultante será semelhante a esta:
```
myfunction/
├── main.py
└── requirements.txt
└── DIRECTORY
   ├── dependency1.whl
   └── dependency2.whl
```
2. Se a dependência for um arquivo tar (*.tar.gz):
  1. Se a dependência estiver escrita em Python, use o pip para fazer o download dela:
```
python3 -m pip download -r requirements.txt \
   -d DIRECTORY
```
  2. Se uma dependência consistir em códigos escritos em C ou C++, faça o download dela e a compile separadamente.
Implante a função e as dependências copiadas:
```
gcloud functions deploy FUNCTION_NAME \
  --runtime PYTHON_RUNTIME_NAME \
  --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
```
Substitua:
- FUNCTION_NAME: o nome da função que você está implantando.
- PYTHON_RUNTIME_NAME: o nome de um dos ambientes de execução Python compatíveis para executar a função implantada em, por exemplo, python311. Precisa ser a mesma versão do ambiente de execução do Python usada no ambiente de desenvolvimento local.
- DIRECTORY: o nome do diretório que contém as dependências copiadas.

Para mais detalhes sobre o uso de buildpacks, consulte Criar uma função com buildpacks.

Usar dependências particulares

É possível usar dependências particulares do Artifact Registry ou de outros repositórios.

Dependências particulares do Artifact Registry

Um repositório Python do Artifact Registry hospeda dependências particulares para sua função Python. Ao implantar no Cloud Run, o processo de build gera automaticamente credenciais do Artifact Registry para a conta de serviço do Cloud Build. Inclua o URL do Artifact Registry no requirements.txt sem gerar outras credenciais. Exemplo:

--index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

Se o build precisar de vários repositórios, use um repositório virtual do Artifact Registry para controlar com segurança a ordem de pesquisa do pip nos repositórios.

Dependências particulares de outros repositórios

Os buildpacks instalam dependências em um ambiente do Cloud Build que não fornece acesso a chaves SSH. Copie os pacotes hospedados em repositórios que exigem autenticação baseada em SSH e faça upload deles com o código do projeto.

Use o comando pip install com a flag -t DIRECTORY para copiar dependências privadas em um diretório local antes de implantar o app, da seguinte maneira:

Copie sua dependência em um diretório local:
```
pip install -t DIRECTORY DEPENDENCY
```
Adicione um arquivo __init__.py vazio ao diretório DIRECTORY para transformá-lo em um módulo.
Importe deste módulo para usar sua dependência:
```
import DIRECTORY.DEPENDENCY
```

Pacotes pré-instalados

O buildpack do Python instala os seguintes pacotes Python ao implantar sua função. Se você estiver usando qualquer um desses pacotes no seu código de função, inclua as seguintes versões no arquivo requirements.txt:

Para evitar problemas com atualizações de versão de dependência, fixe o pacote em uma versão específica.

anyio==4.5.2
blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
exceptiongroup==1.3.0
Flask==3.0.3
functions-framework==3.9.1
gunicorn==23.0.0
h11==0.16.0
idna==3.10
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
sniffio==1.3.1
# Install starlette 0.44.0 for Python 3.8
starlette==0.44.0; python_version == '3.8'
# Install starlette 0.49.1 for Python versions greater than 3.8
starlette==0.49.1; python_version > '3.8'
typing_extensions==4.13.2
uvicorn==0.33.0
uvicorn-worker==0.2.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

O buildpack do Python instala os seguintes pacotes fixados em uma versão específica:

pip (versão mais recente)
setuptools (versão mais recente)
wheel (determinado pelos requisitos do produto)

O ambiente de execução do Python também inclui vários pacotes do sistema no ambiente de execução.

Especificar dependências no Python Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.