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 o Python 3.13 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 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"
    

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

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

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 se aplica se você estiver criando a imagem do contêiner diretamente usando pack build fora do processo de implantação de origem do Cloud Run.

O buildpack do Python é compatível com frameworks da Web modernos, como FastAPI, Gradio e Streamlit.

Python versão 3.12 e anteriores

Se você estiver usando o Python 3.12 ou versões anteriores, o buildpack do Python usará o Gunicorn (em inglês) 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 versão 3.13 e mais recente

Para o Python versão 3.13 e mais recentes, 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 arquivo requirements.txt. Essa configuração padrão se aplica apenas a implantações de origem de serviço do Cloud Run, não a funções do Cloud Run.

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 como padrão a versão mais recente compatível do Python. O buildpack determina o ponto de entrada padrão com base no servidor da Web ou no framework que você configurou no arquivo requirements.txt.

• Se você não especificar um servidor da Web ou um framework no arquivo requirements.txt, o buildpack do Python 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

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

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 o Gunicorn (em inglês) 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 de 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

Pré-lançamento — Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Os buildpacks do Python são compatíveis com projetos configurados com o arquivo pyproject.toml. Com esse recurso, é possível implantar aplicativos gerenciados com Poetry, uv ou pip diretamente no Cloud Run e no 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á precedência.

Configurações de buildpacks compatíveis

Os buildpacks do Python são compatíveis com as seguintes configurações:

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

  • 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ê definiu a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER como pip.

• Buildpack uv: compatível com 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: compatível com projetos Python gerenciados com o 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 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 passará para a próxima etapa.

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

3. Se a configuração do Poetry não for detectada, o buildpack vai procurar um arquivo uv.lock. Se encontrado, o processo de build usa o 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 arquivo pyproject.toml sem uv ou Poetry, o buildpack vai usar uv por 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 pacote de build procura um ponto de entrada na seguinte ordem de precedência:

1. Se um Procfile existir no diretório raiz ou se 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 que você configura 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 o gunicorn para projetos pyproject.toml. Para usar gunicorn ou qualquer outro servidor, adicione-o explicitamente às dependências no arquivo pyproject.toml.

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