Criar um aplicativo em Python

Os buildpacks permitem a configuração idiomática de linguagem por meio de variáveis de ambiente.

Especificar a versão do Python

Por padrão, o buildpack do ambiente de execução Python usa a versão estável mais recente do interpretador de Python. Se seu aplicativo exigir uma versão específica, inclua um arquivo .python-version no diretório raiz do aplicativo especificando essa versão.

3.14

Usar GOOGLE_PYTHON_VERSION

Também é possível especificar a versão do Python usando a variável de ambiente GOOGLE_PYTHON_VERSION. Se as duas configurações forem definidas, o valor GOOGLE_PYTHON_VERSION terá prioridade sobre o arquivo .python-version. Por padrão, quando o arquivo .python-version e a variável de ambiente GOOGLE_PYTHON_VERSION não são especificados, a versão LTS mais recente do Python é usada.

Para configurar o buildpack para usar uma versão compatível do Python ao implantar o app:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.14.x"

Também é possível usar um descritor de projeto project.toml para codificar a variável de ambiente com os arquivos do projeto. Veja instruções sobre como criar o aplicativo com variáveis de ambiente.

Especificar as dependências

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

• Use um arquivo requirements.txt no diretório raiz. Esse arquivo precisa estar no mesmo diretório do 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 pyproject.toml arquivo.

  Se o aplicativo usar os arquivos pyproject.toml e requirements.txt, o arquivo requirements.txt terá prioridade.

  • 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"
    

Gerenciador de pacotes

Se você gerenciar as dependências usando um requirements.txt file, o gerenciador de pacotes padrão vai variar com base na 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 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 pyproject.toml arquivo.

Python 3.14 e versões mais recentes

A partir da versão 3.14 do Python, o buildpack do Python usa o uv gerenciador de pacotes como o instalador padrão para as dependências especificadas no arquivo requirements.txt.

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

Python 3.13 e versões anteriores

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

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

Configurar o pip

É possível configurar o comportamento do pip usando variáveis de ambiente:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Dependências particulares do Artifact Registry

Um repositório Python do Artifact Registry pode hospedar dependências particulares para sua função Python. Ao criar um aplicativo no Cloud Build, o buildpack do Python gera automaticamente as credenciais do Artifact Registry para a conta de serviço do Cloud Build. Só é preciso incluir o URL do Artifact Registry no requirements.txt sem gerar outras credenciais. Exemplo:

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

Ponto de entrada do aplicativo

A seção a seguir descreve o ponto de entrada padrão para o buildpack do Python.

Ponto de entrada para implantações de origem do Cloud Run

Esse recurso só está disponível se você implantar o código-fonte no Cloud Run com o ambiente de execução do Python. Esse recurso não é aplicável se você estiver criando a imagem de contêiner diretamente usando pack build fora do processo de implantação de origem do Cloud Run.

O buildpack do Python oferece suporte a frameworks da Web modernos, como FastAPI, Gradio, Streamlit e Kit de Desenvolvimento de Agente (ADK).

Python 3.12 e versões anteriores

Se você estiver usando o Python 3.12 e versões anteriores, o Python buildpack vai usar o Gunicorn como o servidor HTTP WSGI padrão para sua carga de trabalho. O buildpack do Python define o ponto de entrada padrão como gunicorn -b :8080 main:app.

Python 3.13 e versões mais recentes

Para a versão 3.13 e mais recentes do Python, o buildpack do Python define o ponto de entrada padrão para implantações de origem do Cloud Run com base na configuração do servidor da Web ou do framework no seu requirements.txt arquivo. Essa configuração padrão se aplica apenas às implantações de origem do serviço do Cloud Run, não às Cloud Run functions.

Ao implantar um serviço do Cloud Run da origem usando o ambiente de execução do Python, o buildpack determina a versão do Python e o ponto de entrada padrão das seguintes maneiras:

• Se você não especificar uma versão do Python nos arquivos de origem, o buildpack do Python vai definir o padrão como a versão mais recente do Python compatível. O buildpack determina o ponto de entrada padrão com base no servidor da Web ou no framework configurado no arquivo requirements.txt.

• Se você não especificar um servidor da Web ou um framework no arquivo requirements.txt, o buildpack do Python vai usar o Gunicorn como o servidor HTTP WSGI padrão para sua carga de trabalho. O buildpack do Python define o ponto de entrada padrão como gunicorn -b :8080 main:app.

• O buildpack do Python define o ponto de entrada padrão com base na seguinte ordem de precedência, conforme definido no arquivo requirements.txt:

  1. gunicorn
  2. uvicorn
  3. fastapi[standard]
  4. gradio
  5. streamlit
  6. google-adk

Configurar o servidor da Web ou o framework

Para cada configuração comum do Python no arquivo requirements.txt, a tabela a seguir mostra os pontos de entrada padrão ao implantar no Cloud Run da origem:

Configuração principal	Ponto de entrada padrão	Variáveis de ambiente
gunicorn	gunicorn -b :8080 main:app
numpy	gunicorn -b :8080 main:app
fastapi uvicorn	uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard]	uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn gunicorn	gunicorn -b :8080 main:app
gradio	python main.py	GRADIO_SERVER_NAME=0.0.0.0 GRADIO_SERVER_PORT=8080
streamlit	streamlit run main.py --server.address 0.0.0.0 --server.port 8080
google-adk	adk api_server --host 0.0.0.0 --port 8080

Para evitar falhas de implantação, use uma versão compatível do Python nos arquivos de origem e especifique um servidor da Web no arquivo requirements.txt.

Como alternativa, você também pode especificar o ponto de entrada executando o seguinte comando de implantação de origem:

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

Substitua:

• SERVICE: o nome do serviço em que você quer implantar.
• ENTRYPOINT: o ponto de entrada padrão que você quer usar para o código -fonte.

Se você não conseguir implantar o código-fonte no Cloud Run ou encontrar erros nos registros, consulte o guia de solução de problemas do Cloud Run.

Ponto de entrada para todas as outras implantações

O buildpack do Python usa Gunicorn como o servidor HTTP WSGI padrão para sua carga de trabalho. Os apps criados com o buildpack do Python iniciam o processo gunicorn com configurações padrão, semelhante à execução:

gunicorn --bind :8080 main:app

Personalizar o ponto de entrada do aplicativo

É possível personalizar o comando de inicialização dos aplicativos usando um Procfile ou uma variável de ambiente. Talvez seja necessário fazer isso para personalizar as configurações padrão do ponto de entrada.

Você pode criar um Procfile com suas configurações personalizadas no diretório raiz. Exemplo:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Importante: ao modificar os padrões do Gunicorn, é preciso incluir gunicorn como uma dependência de pacote requirements.txt.

Como alternativa, é possível usar a variável de ambiente GOOGLE_ENTRYPOINT com o comando pack. Exemplo:

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

Variáveis de ambiente

O buildpack do Python é compatível com as variáveis de ambiente a seguir para personalizar o contêiner.

PIP_<key>

Consulte a documentação do pip.

Exemplo:PIP_DEFAULT_TIMEOUT=60 define --default-timeout=60 para comandos pip.

Implantar aplicativos Python com um arquivo pyproject.toml

Os buildpacks do Python oferecem suporte a projetos configurados com o arquivo pyproject.toml. Esse recurso permite implantar aplicativos gerenciados com Poetry, uv ou pip diretamente no Cloud Run e nas Cloud Run functions. Esse recurso não está disponível no App Engine.

O buildpack do Python usa o arquivo pyproject.toml somente quando não há um arquivo requirements.txt no diretório raiz. Se o aplicativo usar os arquivos pyproject.toml e requirements.txt, o arquivo requirements.txt terá prioridade.

Configurações de buildpacks compatíveis

Os buildpacks do Python oferecem suporte às seguintes configurações:

• Buildpack do pip: instala dependências diretamente do pyproject.toml se detectar todas as condições a seguir:

  • Um arquivo pyproject.toml está presente no diretório raiz e você não configura ferramentas de alta precedência, como um arquivo poetry.lock, uma seção [tool.poetry] ou um arquivo uv.lock.

  • Você define a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER como pip.

• Buildpack uv: oferece suporte a projetos Python gerenciados com uv. Esse buildpack é ativado se detectar alguma das seguintes condições:

  • Um arquivo uv.lock e um arquivo pyproject.toml estão presentes na raiz do projeto.
  • Um arquivo pyproject.toml está presente na raiz do projeto e você define a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER como uv.
  • Um arquivo pyproject.toml está presente e você não inclui outros arquivos de bloqueio de alta precedência, como poetry.lock, uv.lock ou configurações como [tool.poetry], e não define a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER.

• Buildpack do Poetry: oferece suporte a projetos Python gerenciados com Poetry. Esse buildpack é ativado se detectar alguma das seguintes condições:

  • Um arquivo poetry.lock e um arquivo pyproject.toml estão presentes na raiz do projeto.
  • Um arquivo pyproject.toml está presente na raiz do projeto e uma seção [tool.poetry] está presente no arquivo pyproject.toml.

Precedência do gerenciador de pacotes

Os buildpacks do Python determinam o gerenciador de pacotes padrão com base na configuração na seguinte ordem de precedência:

1. A maior precedência é dada ao arquivo requirements.txt. Somente se esse arquivo estiver presente, o buildpack do Python vai usar o gerenciador de pacotes padrão para instalar dependências na etapa de build. Se um arquivo requirements.txt não estiver presente, o processo de detecção vai passar para a próxima etapa.

2. Em seguida, o buildpack verifica o arquivo pyproject.toml para um arquivo poetry.lock ou uma seção [tool.poetry]. Se encontrado, o processo de build vai usar o Poetry para instalar dependências.

3. Se a configuração do Poetry não for detectada, o buildpack vai verificar um arquivo uv.lock. Se encontrado, o processo de build vai usar uv para instalar dependências.

4. Se os arquivos de bloqueio não estiverem presentes, o buildpack vai verificar a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER para uma configuração pip ou uv.

5. Padrão. Se você não definir uma variável de ambiente e usar apenas um pyproject.toml arquivo sem uv ou Poetry, o buildpack vai usar uv como padrão para todas as versões compatíveis do Python.

Ponto de entrada com um arquivo pyproject.toml

Ao implantar um aplicativo com um arquivo pyproject.toml em vez de usar um arquivo requirements.txt, o buildpack do Python usa um método diferente para determinar o ponto de entrada. Para informações sobre como configurar um ponto de entrada do aplicativo com um arquivo requirements.txt, consulte Ponto de entrada do aplicativo.

O buildpack procura um ponto de entrada na seguinte ordem de precedência:

1. Se um Procfile existir no diretório raiz ou você configurar a variável de ambiente GOOGLE_ENTRYPOINT, essas configurações sempre vão substituir qualquer ponto de entrada determinado por scripts pyproject.toml.

2. O buildpack do Python usa os scripts personalizados configurados nas seções [tool.poetry.scripts] e [project.scripts]. Se você configurar um script que inclua start, esse será seu ponto de entrada. Por exemplo, poetry run start ou uv run start.

3. Se você não configurar um script start, mas definir outro script, o script definido será o ponto de entrada padrão. Por exemplo, poetry run mycmd ou uv run mycmd.

Ao contrário dos builds baseados em requirements.txt, o buildpack do Python não instala automaticamente gunicorn para projetos pyproject.toml. Para usar gunicorn ou qualquer outro servidor, é necessário adicioná-lo explicitamente às dependências no arquivo pyproject.toml.

Se você não configurar scripts personalizados no arquivo pyproject.toml, os buildpacks vão tentar detectar frameworks comuns, como gunicorn, uvicorn ou fastapi das dependências pyproject.toml e determinar um ponto de entrada padrão.