Python Workers no Cloudflare: o guia completo do primeiro deploy de uma API real

O que a Cloudflare está entregando aqui

A documentação de Python↳Python56 conteúdosVSCode + Python + Alexa: Desenvolva e teste skills para alexa localmente com pythonDev (Back & Front) · out 2025Dominando decoradores em Python: um guia completo com exemplosDev (Back & Front) · jan 2025Desenvolvimento de software: diferenças entre Python, JavaScript e JavaGestão Dev & TI · nov 2024Ver tudo em Dev (Back & Front) → Workers, atualizada em 17 de setembro de 2026, descreve um runtime que executa Python dentro dos Workers com suporte a pacotes como FastAPI, Langchain e Pydantic, uma interface de função estrangeira (FFI) para chamar objetos e funções JavaScript direto do Python, e acesso a praticamente todo o ecossistema de bindings da plataforma: KV, D1, Durable Objects, Workers AI↳Inteligência artificial440 conteúdosUX e IA: Transformando Experiências Digitais com Inteligência ArtificialProduto & UX · jan 2025MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025IA generativa e a urgência de reconstruir nossa relação com a verdadeAI · jun 2025Ver tudo em AI →, Vectorize, R2, Queues e Workflows. Isso é mais do que "Python roda no edge": é Python com as mesmas portas de entrada que um Worker em JavaScript já tinha.

O caminho que segui abaixo é o oficial, documentado pela própria Cloudflare. Não medi cold start em produção com carga real porque a documentação consultada não publica esses números, e eu não vou inventar benchmark que não existe na fonte. O que dá para fazer, e é o que este guia entrega, é montar o Worker do zero, publicar de verdade e saber exatamente onde procurar os números de cold start no seu próprio ambiente antes de tomar a decisão de migrar.

Pré-requisitos

Antes de tocar em código, você precisa de duas ferramentas instaladas: uv (o gerenciador de pacotes e ambientes Python que a Cloudflare adotou como base) e Node.js, exigido pelo toolchain do Workers. Sem qualquer um dos dois o pywrangler simplesmente não roda.

Com os dois prontos, o ponto de entrada é o pywrangler, a CLI dedicada a Python Workers (equivalente ao wrangler do mundo JavaScript). Ela cuida de três coisas: inicializar o projeto, rodar localmente e publicar.

Criando o projeto

O comando de bootstrap é direto:

uvx --from workers-py pywrangler init

Esse comando cria um pyproject.toml com workers-py como dependência de desenvolvimento e gera o arquivo de configuração do Wrangler. A partir daqui, o projeto já é gerenciado via uv, então os comandos seguintes usam uv run na frente.

Se preferir começar de um exemplo real em vez de partir do zero, a Cloudflare mantém um repositório de referência:

git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/hello

É o caminho mais rápido para ver a estrutura de pastas de um Worker Python funcionando antes de escrever a sua.

O Worker mais simples possível

A documentação oficial resume a estrutura mínima em quatro linhas, e é exatamente esse o código que fica no arquivo de entrada do projeto:

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello World!")

Duas coisas para notar aqui, se você vem de Flask ou FastAPI: primeiro, o handler não é uma função solta decorada com rota, é um método fetch() dentro de uma classe Default que estende WorkerEntrypoint, o roteamento por caminho e verbo HTTP, se você quiser, fica por sua conta dentro desse método ou delegado a um framework como FastAPI. Segundo, o handler é async por padrão, porque o runtime dos Workers é orientado a event loop desde a base, não uma opção que você liga depois.

Rodando localmente

Com o projeto criado, o ciclo de desenvolvimento é:

uv run pywrangler dev

Isso levanta um servidor local que simula o runtime dos Workers, incluindo o comportamento do isolado Python. É aqui que você testa a lógica antes de gastar um deploy real, e é o único ambiente onde vale a pena iterar rápido em cima de erros de importação de pacote, porque o ciclo de build de um Worker Python (que precisa empacotar as dependências) não é instantâneo.

Publicando de verdade

Quando o dev está satisfatório, o deploy é uma linha:

uv run pywrangler deploy

Esse comando empacota o Worker, resolve as dependências declaradas no pyproject.toml e publica na rede da Cloudflare. Não há passo intermediário de build separado que a documentação exija manualmente: o pywrangler cuida disso.

Dependências de terceiros: onde a promessa fica mais interessante (e mais escorregadia)

A razão de existir de Python Workers não é rodar Hello World, é rodar bibliotecas reais. A documentação cita nominalmente FastAPI, Langchain e Pydantic como pacotes com instalação fácil e boot rápido nesse runtime, mas o texto da própria página remete às "páginas de pacotes" para o passo a passo detalhado de cada biblioteca, sem detalhar aqui a sintaxe exata de instalação.

Na prática, como o projeto já é gerenciado por uv, o caminho natural é declarar a dependência no pyproject.toml (manualmente ou via uv add nome-do-pacote) e deixar o pywrangler empacotar tudo no próximo dev ou deploy. Antes de assumir que qualquer pacote do PyPI vai funcionar, vale checar a página de pacotes suportados: pacotes com extensões nativas em C que não têm build compatível com o ambiente de execução do Workers simplesmente não sobem.

Em resumo: o suporte a FastAPI, Langchain e Pydantic é explícito e testado pela Cloudflare; qualquer outro pacote merece uma checagem antes de virar dependência de produção.

Bindings: o que muda de fato em relação a rodar Flask numa VM

A diferença real entre um Worker Python e uma API Flask tradicional não está na sintaxe do handler, está no acesso nativo aos serviços da plataforma via bindings, sem precisar instanciar SDK nem gerenciar credencial de conexão:

Somado a isso, a FFI (interface de função estrangeira) permite chamar objetos e funções JavaScript direto do código Python, incluindo todas as Runtime APIs do Workers. Isso é diferente de qualquer coisa que exista num Flask rodando numa VM: lá, cada um desses serviços seria uma chamada de rede para um provedor externo, com sua própria autenticação e sua própria latência de rede.

Cold start: o que a documentação não me deu, e o que eu faria no seu lugar

Aqui está a parte em que preciso ser honesto sobre o limite deste guia: a página oficial de Python Workers que usei como base não publica número de cold start, nem lista "três técnicas oficiais de mitigação". Ela promete pacotes "fast-booting", mas não quantifica isso. Eu não vou inventar milissegundo que não está na fonte, e você não deveria confiar em benchmark de terceiros sem reproduzir no seu próprio Worker.

O que eu recomendaria, num projeto real: antes de decidir se cold start é um problema para o seu caso, meça você mesmo com a observabilidade↳Observabilidade11 conteúdosObservabilidade para APIs: os desafios e benefícios dessa abordagemDev (Back & Front) · jan 2025Falhas em Observabilidade afetam os Apps e a Segurança das OrganizaçõesDev (Back & Front) · nov 2023ADK Java 1.0: O Google quer que você pare de gambiarra Python no seu backendMarketing Tech · abr 2026Ver tudo em DevSecOps → nativa do Workers (Wrangler tail e Analytics), comparando o tempo de resposta na primeira requisição de um isolado frio contra as seguintes. O carregamento inicial do interpretador Python e das dependências importadas é o suspeito natural de qualquer atraso, mas isso é leitura minha sobre como a arquitetura provavelmente funciona, não um dado publicado pela Cloudflare nesta documentação.

Vale trocar Flask ou FastAPI tradicional por isso?

Depende do que você está otimizando. Se o seu serviço já vive numa VM ou container com pool de processos quente, trocar por Workers só para ganhar "edge" sem medir cold start é trocar um problema conhecido por um desconhecido. Se, por outro lado, o gargalo hoje é gerenciar infraestrutura, escalar por região e manter credenciais de banco e cache espalhadas, os bindings nativos (KV, D1, R2) tiram uma camada inteira de complexidade operacional que Flask nunca resolveu por conta própria.

Contexto é rei aqui, de verdade: para uma API interna de baixo tráfego que já roda estável em Flask, a migração provavelmente não paga o custo de reescrever o roteamento. Para um serviço novo, com necessidade de baixa latência global e uso pesado de KV ou Workers AI, começar direto em Python Workers evita meses de trabalho de integração que você teria que fazer manualmente num Flask tradicional.

Fonte: Cloudflare Workers — Python Language Support