Como hospedar um script ou API em Python

Um app Python funciona na sua máquina porque ali estão a versão certa do Python, as bibliotecas instaladas e as variáveis que você configurou. Hospedar é reproduzir esse ambiente num servidor que fica ligado o tempo todo.

Existem dois casos comuns. Um script executa trabalho sem receber visitas: um bot, um coletor de dados, uma tarefa agendada. Uma API escuta em uma porta e responde requisições. O caminho é o mesmo para os dois, com uma diferença: só a API precisa de porta. Para a visão geral, veja o que é deploy.

O que você precisa antes de hospedar?#

• Uma versão de Python definida. Use a mesma localmente e em produção.
• Um requirements.txt com as dependências e suas versões.
• Um arquivo principal (aqui, main.py) que inicia tudo.
• Um lugar para rodar: VPS, container ou plataforma de hospedagem. A diferença está em VPS vs plataforma de nuvem.

Qual versão? Para um projeto novo, prefira uma versão do Python em fase de correção de bugs (bugfix), desde que todas as suas dependências já publiquem pacotes para ela. As versões mais antigas passam a receber só correções de segurança e depois chegam ao fim da vida. O calendário oficial mostra a fase de cada versão.

Como preparar o projeto com venv?#

O venv é um ambiente isolado, só deste projeto, que impede que as bibliotecas de um app entrem em conflito com as de outro.

mkdir meu-app && cd meu-app
python -m venv .venv
source .venv/bin/activate        # Windows (PowerShell): .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install fastapi uvicorn
python -m pip freeze > requirements.txt

O pip freeze grava as versões instaladas no requirements.txt. No servidor, python -m pip install -r requirements.txt recria o mesmo ambiente. Por isso a pasta .venv não sobe: ela guarda caminhos absolutos e não é portátil. Coloque .venv/ e .env no .gitignore.

Como escrever um script que roda sem parar?#

Um script de longa duração precisa ler a configuração do ambiente, sobreviver a um erro isolado e parar direito quando o servidor pedir. Esse pedido chega pelo sinal SIGTERM, em reinícios e deploys.

import os
import signal
import sys
import time
import urllib.request

stopping = False


def handle_stop(signum, frame):
    global stopping
    stopping = True


signal.signal(signal.SIGTERM, handle_stop)
signal.signal(signal.SIGINT, handle_stop)

API_URL = os.environ.get("API_URL")
if not API_URL:
    sys.exit("API_URL não está definida")
INTERVAL = int(os.environ.get("INTERVAL_SECONDS", "60"))


def job():
    with urllib.request.urlopen(API_URL, timeout=10) as response:
        print(f"status {response.status}", flush=True)


while not stopping:
    try:
        job()
    except Exception as exc:  # um erro isolado não derruba o processo
        print(f"tarefa falhou: {exc}", flush=True)
    for _ in range(INTERVAL):  # dorme de 1 em 1 segundo para notar o SIGTERM logo
        if stopping:
            break
        time.sleep(1)

print("encerrando", flush=True)

O que cada parte faz:

• os.environ: URL e intervalo vêm do ambiente, não do código. Se faltar API_URL, o script falha na hora com uma mensagem clara.
• stopping: o handler só muda uma variável, e quem encerra é o laço principal. A espera acontece em passos de 1 segundo, então o script percebe o SIGTERM em até um segundo, mesmo com um intervalo longo.
• flush=True: quando a saída não é um terminal, o Python guarda o print em buffer e os logs chegam atrasados. Rodar com python -u ou definir PYTHONUNBUFFERED=1 tem o mesmo efeito.

Teste local: API_URL=https://example.com python main.py. Para tarefas que rodam em horários fixos, veja o que é um cron job.

Como hospedar uma API em Python?#

Uma API precisa de um servidor ASGI. O mais usado com FastAPI é o Uvicorn. O app mínimo:

from fastapi import FastAPI

app = FastAPI()


@app.get("/health")
def health():
    return {"status": "ok"}

Inicie com:

uvicorn main:app --host 0.0.0.0 --port "${PORT:-8000}"

Dois detalhes importam em produção. Primeiro, --host 0.0.0.0: o padrão escuta só em 127.0.0.1, e de fora do container ou da máquina ninguém alcança o app. Segundo, a porta vem da variável PORT quando a plataforma a define, com 8000 como padrão de desenvolvimento.

Para comparar os frameworks, veja como hospedar FastAPI, Flask e Django. O que revisar antes de abrir ao público está no checklist de API em produção.

Como lidar com variáveis de ambiente e segredos?#

Tokens, senhas de banco e chaves de API ficam em variáveis de ambiente, nunca no repositório. Localmente, use um arquivo .env fora do Git e exporte as variáveis antes de rodar, ou use python-dotenv. Em produção, defina cada uma no painel do provedor. O padrão completo está em o que são variáveis de ambiente.

Como verificar que funcionou?#

1. Logs: devem mostrar o início do script ou o Uvicorn escutando, sem traceback depois.
2. Requisição: chame /health no endereço público e espere {"status":"ok"}.
3. Reinício: reinicie o app e confirme que ele volta sozinho e que o SIGTERM gera a linha "encerrando".

Quais são os erros mais comuns?#

• ModuleNotFoundError: No module named 'fastapi': a dependência não foi instalada ou não está no requirements.txt. Rode pip freeze de novo com o venv ativo.
• Erro ao instalar ou compilar um pacote: a versão do Python no servidor é diferente da local, e a biblioteca ainda não tem pacote pronto para ela. Alinhe as versões.
• O app sobe mas o site não abre: o servidor escuta em 127.0.0.1 ou em uma porta fixa. Use 0.0.0.0 e a porta do ambiente.
• Logs vazios ou atrasados: buffer de saída. Use flush=True ou PYTHONUNBUFFERED=1.
• Funciona local, cai em produção: variável de ambiente ausente ou pouca memória. Compare os dois ambientes. Se o problema for memória, veja dimensionamento de RAM e CPU.
• O script morre e não volta: nada o reinicia. Use um servidor ou container com política de reinício. Para empacotar, veja como containerizar um app.

Como fazer isso na Square Cloud#

Os dois casos deste guia viram dois tipos de aplicação na Square Cloud. Você envia o projeto por ZIP no painel, pela CLI, pelo GitHub (um push dispara o deploy) ou pela extensão do VS Code, e no start a plataforma roda pip install -r requirements.txt, o mesmo arquivo que você gerou no venv. A saída da instalação aparece nos logs, então um ModuleNotFoundError mostra na hora qual pacote faltou. O arquivo squarecloud.app é opcional: o painel o gera no deploy.

O script roda como aplicação de fundo, sem subdomínio: o formulário de deploy detecta o main.py, e o processo usa a partir de 256 MB da RAM do plano, sem receber tráfego de entrada. A API é uma aplicação web, com no mínimo 512 MB e um subdomínio *.squareweb.app com HTTPS. Como o main.py com FastAPI só define o app, preencha o comando de início com uvicorn main:app --host 0.0.0.0 --port $PORT; a plataforma define a variável PORT.

API_URL e INTERVAL_SECONDS entram como variáveis de ambiente da aplicação no painel, que também importa um .env; elas já existem durante a instalação e valem no próximo restart. O container fica sempre ligado, e o reinício automático, ligado por padrão no deploy pelo painel, traz o processo de volta quando ele encerra com erro. Um estouro de memória, ao contrário, para a aplicação até você aumentar a RAM. Mantenha o flush=True ou o PYTHONUNBUFFERED=1 para ver cada linha nos logs em tempo real.

A RAM do plano é um pool compartilhado: no Hobby, que começa em R$ 12,49 por mês com 1 GB, um script com 256 MB e uma API com 512 MB cabem juntos. O Python é um entre diversos runtimes, ao lado de Node.js, Go e Java: veja os runtimes disponíveis hoje em Runtimes e os detalhes do runtime Python.