Crie uma aplicação Python

Os buildpacks suportam a configuração idiomática da linguagem através de variáveis de ambiente.

Especifique a versão do Python

Por predefinição, o buildpack do Python Runtime usa a versão estável mais recente do intérprete Python. Se a sua aplicação exigir uma versão específica, pode especificar uma incluindo um ficheiro .python-version no diretório raiz da aplicação.

3.14

Usar GOOGLE_PYTHON_VERSION

Também é possível especificar a versão do Python através da variável de ambiente GOOGLE_PYTHON_VERSION. Se ambas as configurações estiverem definidas, o valor GOOGLE_PYTHON_VERSION tem prioridade sobre o ficheiro .python-version. Por predefinição, quando o ficheiro .python-version e a variável do ambiente GOOGLE_PYTHON_VERSION não são especificados, é usada a versão LTS mais recente do Python.

Para configurar o buildpack para usar o Python 3.13 quando implementar a sua app:

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

Também pode usar um descritor de projeto project.toml para codificar a variável de ambiente juntamente com os ficheiros do projeto. Veja instruções sobre como criar a aplicação com variáveis de ambiente.

Especifique dependências

Especifique as dependências da sua aplicação para as versões do Python suportadas através de qualquer uma das seguintes abordagens:

• Use um ficheiro requirements.txt no diretório raiz. Este ficheiro tem de estar no mesmo diretório que o ficheiro main.py que contém o seu código-fonte. O ficheiro requirements.txt contém uma linha por pacote. Cada linha contém o nome do pacote e, opcionalmente, a versão pedida. Para evitar que a compilação seja afetada por alterações à versão das dependências, considere afixar os pacotes de dependências a uma versão específica.

  Segue-se um exemplo de um ficheiro requirements.txt:

  functions-framework
  requests==2.20.0
  numpy
  

• Use um ficheiro pyproject.toml para especificar dependências. Se gerir as dependências da sua aplicação num ficheiro pyproject.toml em vez do ficheiro requirements.txt, o buildpack do Python determina o gestor de pacotes com base na configuração que especificar no ficheiro pyproject.toml. Para mais informações, consulte o artigo Implemente aplicações Python com um ficheiro pyproject.toml.

  Se a sua aplicação usar o ficheiro pyproject.toml e o ficheiro requirements.txt, o ficheiro requirements.txt tem precedência.

  • Segue-se um exemplo de um ficheiro 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"
    

Gestor de pacotes

Se gerir as suas dependências através de um requirements.txt file, o gestor de pacotes predefinido varia consoante a versão do Python que configurar.

Se usar um ficheiro pyproject.toml para gerir dependências em vez de um ficheiro requirements.txt, o buildpack do Python determina o gestor de pacotes com base nas definições de configuração no ficheiro pyproject.toml. O buildpack suporta os gestores de pacotes pip, uv e Poetry. Para mais informações, consulte o artigo Implemente aplicações Python com um ficheiro pyproject.toml.

Python 3.14 e posteriores

A partir da versão 3.14 (pré-visualização) do Python e posteriores, o buildpack do Python usa o gestor de pacotes uv como o instalador predefinido para as dependências que especificar no ficheiro requirements.txt.

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

Python 3.13 e anteriores

Para a versão 3.13 e anteriores do Python, o buildpack do Python usa o gestor de pacotes pip para instalar as dependências que define no ficheiro requirements.txt.

Para usar uv (pré-visualização) como gestor de pacotes, configure a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

Configure o PIP

É possível configurar o comportamento do pip através de variáveis de ambiente:

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

Dependências privadas do Artifact Registry

Um repositório Python do Artifact Registry pode alojar dependências privadas para a sua função Python. Quando cria uma aplicação no Cloud Build, o buildpack do Python gera automaticamente credenciais do Artifact Registry para a conta de serviço do Cloud Build. Só tem de incluir o URL do Artifact Registry no seu requirements.txt sem gerar credenciais adicionais. Por exemplo:

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

Ponto de entrada da aplicação

A secção seguinte descreve o ponto de entrada predefinido para o buildpack do Python.

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

Esta funcionalidade só está disponível se implementar o seu código fonte no Cloud Run com o tempo de execução do Python. Esta funcionalidade não é aplicável se estiver a criar a imagem do contentor diretamente com o comando pack build fora do processo de implementação de origem do Cloud Run.

O Python buildpack suporta frameworks Web modernos, como FastAPI, Gradio e Streamlit.

Versão 3.12 e anteriores do Python

Se estiver a usar a versão 3.12 e anteriores do Python, o buildpack do Python usa o Gunicorn por predefinição como o servidor HTTP WSGI para a sua carga de trabalho. O buildpack do Python define o ponto de entrada predefinido como gunicorn -b :8080 main:app.

Versão 3.13 e posteriores do Python

Para a versão 3.13 e posteriores do Python, o buildpack do Python define o ponto de entrada predefinido para implementações de origem do Cloud Run com base na configuração do servidor Web ou da framework no seu ficheiro requirements.txt. Esta definição predefinida aplica-se apenas a implementações de origem de serviços do Cloud Run e não a funções do Cloud Run.

Quando implementa um serviço do Cloud Run a partir da origem usando o tempo de execução do Python, o buildpack determina a versão do Python e o ponto de entrada predefinido das seguintes formas:

• Se não especificar uma versão do Python nos seus ficheiros de origem, o buildpack do Python define a predefinição para a versão do Python mais recente suportada. O buildpack determina o ponto de entrada predefinido com base no servidor Web ou na framework que configurou no ficheiro requirements.txt.

• Se não especificar um servidor Web ou uma framework no ficheiro requirements.txt, o buildpack do Python usa o Gunicorn como o servidor HTTP WSGI para a sua carga de trabalho por predefinição. O buildpack do Python define o ponto de entrada predefinido como gunicorn -b :8080 main:app.

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

  1. gunicorn
  2. uvicorn
  3. fastapi[standard]
  4. gradio
  5. streamlit

Configure o servidor Web ou a framework

Para cada configuração comum do Python no ficheiro requirements.txt, a tabela seguinte mostra os pontos de entrada predefinidos quando a implementação é feita no Cloud Run a partir da origem:

Configuração principal	Ponto de entrada predefinido	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 implementação, use uma versão do Python suportada nos seus ficheiros de origem e especifique um servidor Web no ficheiro requirements.txt.

Em alternativa, também pode especificar o ponto de entrada executando o seguinte comando de implementação de origem:

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

Substitua o seguinte:

• SERVICE: o nome do serviço para o qual quer fazer a implementação.
• ENTRYPOINT: o ponto de entrada predefinido que quer usar para o seu código fonte.

Se não conseguir implementar o código-fonte no Cloud Run ou encontrar erros nos registos, consulte o guia de resolução de problemas do Cloud Run.

Ponto de entrada para todas as outras implementações

O buildpack do Python usa o Gunicorn como o servidor HTTP WSGI predefinido para a sua carga de trabalho. As apps criadas com o buildpack do Python iniciam o processo gunicorn com as predefinições, semelhante à execução do seguinte comando:

gunicorn --bind :8080 main:app

Personalize o ponto de entrada da aplicação

Pode personalizar o comando de início das aplicações através de um Procfile ou de uma variável de ambiente. Pode ter de o fazer para personalizar as configurações do ponto de entrada predefinido.

Pode criar um Procfile com as suas definições personalizadas no diretório raiz. Exemplo:

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

Importante: quando substitui as predefinições do Gunicorn, tem de incluir gunicorn como uma dependência do pacote no ficheiro requirements.txt do seu projeto.

Em alternativa, pode 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 suporta as seguintes variáveis de ambiente para personalizar o seu contentor

PIP_<key>

Consulte a documentação do pip.

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

Implemente aplicações Python com um ficheiro pyproject.toml

Pré-visualização — Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Os buildpacks do Python suportam projetos que configura com o ficheiro pyproject.toml. Esta funcionalidade permite-lhe implementar aplicações que gere com o Poetry, o uv ou o pip diretamente no Cloud Run e nas funções do Cloud Run. Esta funcionalidade não está disponível no App Engine.

O buildpack do Python usa o ficheiro pyproject.toml apenas quando não existe um ficheiro requirements.txt no diretório raiz. Se a sua aplicação usar o ficheiro pyproject.toml e o ficheiro requirements.txt, o ficheiro requirements.txt tem precedência.

Configurações de buildpacks suportadas

Os buildpacks do Python suportam as seguintes configurações:

• pip buildpack: instala as dependências diretamente a partir de pyproject.toml se detetar todas as seguintes condições:

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

  • Definiu a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER como pip.

• uv buildpack: suporta projetos Python que gere com o uv. Este buildpack é ativado se detetar alguma das seguintes condições:

  • Estão presentes um ficheiro uv.lock e um ficheiro pyproject.toml na raiz do projeto.
  • Um ficheiro pyproject.toml está presente na raiz do projeto e define a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER como uv.
  • Um ficheiro pyproject.toml está presente e não inclui outros ficheiros 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.

• Poetry buildpack: suporta projetos Python que gere com o Poetry. Este buildpack é ativado se detetar alguma das seguintes condições:

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

Precedência do gestor de pacotes

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

1. A precedência mais elevada é atribuída ao ficheiro requirements.txt. Apenas se este ficheiro estiver presente, o buildpack do Python usa o gestor de pacotes predefinido para instalar dependências no passo de compilação. Se não existir um ficheiro requirements.txt, o processo de deteção avança para o passo seguinte.

2. Em seguida, o buildpack verifica o ficheiro pyproject.toml para um ficheiro poetry.lock ou uma secção [tool.poetry]. Se for encontrado, o processo de compilação prossegue para usar o Poetry para instalar dependências.

3. Se a configuração do Poetry não for detetada, o buildpack procura um ficheiro uv.lock. Se for encontrado, o processo de compilação prossegue para usar o uv para instalar dependências.

4. Se não existirem ficheiros de bloqueio, o buildpack verifica a variável de ambiente GOOGLE_PYTHON_PACKAGE_MANAGER para uma configuração pip ou uv.

5. Predefinição. Se não definir uma variável de ambiente e usar apenas um pyproject.tomlficheiro sem uv ou Poetry, o buildpack usa o uv por predefinição para todas as versões do Python suportadas.

Ponto de entrada com um ficheiro pyproject.toml

Quando implementa uma aplicação com um ficheiro pyproject.toml em vez de usar um ficheiro requirements.txt, o buildpack do Python usa um método diferente para determinar o ponto de entrada. Para obter informações sobre a configuração de um ponto de entrada da aplicação com um ficheiro requirements.txt, consulte o artigo Ponto de entrada da aplicação.

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

1. Se existir um Procfile no diretório raiz ou configurar a variável de ambiente GOOGLE_ENTRYPOINT, estas configurações substituem sempre qualquer ponto de entrada determinado pelos scripts pyproject.toml.

2. O buildpack do Python usa os scripts personalizados que configura nas secções [tool.poetry.scripts] e [project.scripts]. Se configurar um script que inclua start, este é o seu ponto de entrada. Por exemplo, poetry run start ou uv run start.

3. Se não configurar um script start, mas definir outro script, o script que definir é o ponto de entrada predefinido. Por exemplo, poetry run mycmd ou uv run mycmd.

Ao contrário das compilações baseadas no requirements.txt, o buildpack do Python não instala automaticamente o gunicorn para projetos do pyproject.toml. Para usar o gunicorn ou qualquer outro servidor, tem de o adicionar explicitamente às dependências no ficheiro pyproject.toml.

Se não configurar scripts personalizados no ficheiro pyproject.toml, os buildpacks tentam detetar frameworks comuns, como gunicorn, uvicorn ou fastapi, a partir das suas dependências pyproject.toml e determinam um ponto de entrada predefinido.