FastAPI na VPS: como publicar sua API com Nginx
Aprenda a publicar uma API FastAPI na VPS: ambiente virtual, Uvicorn, systemd para manter no ar, Nginx como proxy, cabeçalhos do proxy e HTTPS com Certbot.
Por Redação Eleven Host · @robson.direitodigital · 5 de novembro de 2026 · 10 min de leitura

Capa da Redação Eleven Host para o guia: FastAPI na VPS: como publicar sua API com Nginx Arte: Eleven Host
FastAPI na VPS: veja como publicar uma API FastAPI com Uvicorn, systemd, Nginx e HTTPS, da versão do Python ao teste final pelo domínio.
Se você está começando com servidores, o guia O que é servidor VPS explica o básico da máquina onde a API vai ficar. Aqui, os exemplos usam o domínio fictício api.exemplo.com.br, o usuário deploy e a pasta /home/deploy/api. Troque pelos seus.
Versões e requisitos
Na data da publicação (05/11/2026), o PyPI lista o FastAPI 0.162.0 e o Uvicorn 0.54.0, e os dois pedem Python 3.10 ou mais novo. Esses números são o retrato desse dia; confira as versões atuais antes de começar. A versão do Python do servidor depende da instalação, e o comando abaixo mostra qual é a sua:
python3 --version
Se ela for mais antiga que a 3.10, instale uma versão atual pelo site oficial do Python. O Nginx também tem instruções de instalação no site oficial dele. Depois, confira o resultado com nginx -v.
Enquanto o FastAPI estiver abaixo da versão 1.0.0, uma atualização MINOR pode trazer mudanças que quebram o código, segundo a documentação. Por isso ela manda fixar a versão que funciona para você e ter testes antes de atualizar.
Ambiente virtual e instalação
A documentação do FastAPI recomenda o uv para gerenciar projeto, dependências e ambiente virtual, e trata o fluxo com python -m venv e pip como a alternativa. O exemplo usa a alternativa. Um exemplo de comandos, rodados na pasta do projeto; confira no seu servidor:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "fastapi[standard]"
As aspas em "fastapi[standard]" evitam problemas em alguns terminais. Esse pacote inclui o Uvicorn e a ferramenta de linha de comando fastapi. Para fixar as versões instaladas, um exemplo é gerar o arquivo de requisitos:
pip freeze > requirements.txt
Recomendamos rodar a API com um usuário comum, como o deploy do exemplo, e não com o administrador do servidor.
Um exemplo mínimo de API
Para testar o caminho todo, um exemplo de arquivo main.py com uma única rota, no formato da página inicial da documentação:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root(): return {"Hello": "World"}
O comando fastapi run escuta em 0.0.0.0, ou seja, em cada endereço da máquina, e fica acessível a quem conseguir falar com ela. Por isso, com o Nginx na frente, o exemplo usa o Uvicorn com --host 127.0.0.1, que deixa a API visível só para o próprio servidor.
Uvicorn direto, sem fastapi run
A documentação do FastAPI explica que, em produção, o comando é fastapi run no lugar de fastapi dev, e que por baixo ele usa o Uvicorn. O Uvicorn, se você não indicar outra coisa, escuta em 127.0.0.1, na porta 8000. Um exemplo de comando para testar a API atrás do Nginx:
.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
Com ele rodando, chame a rota local em outra sessão para ver a resposta. Não use a opção --reload em produção: a documentação avisa que ela consome muito mais recursos e é mais instável.
Sobre a documentação da API: o FastAPI publica a página interativa em /docs. Dá para desativar essa página com docs_url=None, a página do ReDoc com redoc_url=None e o esquema OpenAPI inteiro com openapi_url=None. Decida o que deixar público antes de apontar o domínio.
Workers do Uvicorn
A opção --workers do Uvicorn recebe um número e inicia essa quantidade de processos. A documentação do FastAPI explica que o objetivo é aproveitar processadores com vários núcleos. O padrão do Uvicorn é um processo, ou o valor da variável de ambiente WEB_CONCURRENCY, quando ela existe, e a opção não funciona junto com --reload.
Segundo a documentação, os processos diferentes normalmente não compartilham memória. Uma API que carrega um arquivo grande na memória ao iniciar vai carregá-lo uma vez por processo, e o estado guardado em variáveis fica separado em cada um. Por isso, meça o uso de memória da sua API antes de aumentar o número.
A documentação do FastAPI cita o Gunicorn ao contar a história de uma imagem Docker antiga, hoje descontinuada, e este caminho dispensa o Gunicorn. O site do Uvicorn ainda documenta o uso com Gunicorn, avisando que o módulo uvicorn.workers está descontinuado em favor do pacote uvicorn-worker.
Uma VPS entra na conta dos seus próximos meses? VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer os planos
Manter a API no ar com systemd
Rodar o comando à mão tem um problema que a documentação do FastAPI aponta: se a conexão com o servidor cair, o processo provavelmente morre. A mesma documentação diz que é preciso um componente externo para iniciar o processo com o servidor e reiniciá-lo quando ele falhar, e cita o systemd entre as ferramentas possíveis. Um exemplo, com base na documentação do systemd, de /etc/systemd/system/api.service; troque usuário e pastas e confira cada linha:
[Unit]
Description=API FastAPI
After=network.target
[Service]
Type=exec
User=deploy
WorkingDirectory=/home/deploy/api
EnvironmentFile=/etc/api/ambiente
ExecStart=/home/deploy/api/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
Restart=on-failure
[Install]
WantedBy=multi-user.target
Em linhas gerais, segundo a documentação do systemd: Type=exec serve a serviços de longa duração, EnvironmentFile= lê as variáveis de um arquivo de texto, User= define o usuário que executa o processo e Restart=on-failure reinicia o serviço quando o processo sai com código de erro. O arquivo /etc/api/ambiente guarda as variáveis da API, como chaves e endereços de banco. Crie o arquivo antes de ativar o serviço, com uma variável por linha no formato NOME=valor, e restrinja a leitura dele ao usuário da API. Para carregar e ativar o serviço, um exemplo:
sudo systemctl daemon-reload
sudo systemctl enable --now api
Para ver se subiu, use systemctl status api.
Nginx na frente da API
A documentação do Uvicorn indica o Nginx para quem hospeda a própria aplicação, e a do FastAPI cita o Nginx como uma das opções para tratar o HTTPS na frente da API. Um exemplo de configuração, que junta o exemplo do Uvicorn com a página do Nginx sobre WebSocket. Confira cada linha no seu servidor:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name api.exemplo.com.br;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
O bloco map precisa ficar no contexto http do Nginx; veja na sua instalação onde ficam os arquivos de configuração incluídos. O proxy_pass aponta para a porta local da API, e o Host repassa o que o cliente enviou, como no exemplo do Uvicorn. As linhas Upgrade e Connection existem porque o cabeçalho Upgrade não é repassado ao servidor de trás, e servem a quem usa WebSocket. A linha proxy_http_version 1.1 importa nas versões anteriores à 1.29.7 do Nginx, que usavam a 1.0 como padrão.
O exemplo do Uvicorn usa um socket Unix em vez da porta TCP, e a documentação dele recomenda o socket para o proxy com Nginx. Aqui usamos a porta local por simplicidade; se quiser o socket, siga a documentação do Uvicorn. Outro limite a conhecer é o tamanho de upload: o padrão do Nginx é client_max_body_size 1m, e acima disso o cliente recebe o erro 413. Aumente a opção se a sua API recebe arquivos maiores. Depois de editar, teste a sintaxe e recarregue:
sudo nginx -t
sudo nginx -s reload
Cabeçalhos do proxy
Com o Nginx na frente, a API só sabe o endereço e o protocolo originais do visitante pelos cabeçalhos X-Forwarded-For e X-Forwarded-Proto. A documentação do Uvicorn explica que a leitura desses cabeçalhos vem ligada, mas limitada aos IPs listados em --forwarded-allow-ips, e que, sem essa opção, ele confia em 127.0.0.1 e ::1. Como o Nginx do exemplo fala com a API por 127.0.0.1, recomendamos conferir, no seu servidor, se os redirecionamentos da API saem com https e o domínio certo. A mesma documentação alerta para confiar apenas em clientes confiáveis, então não amplie a lista sem necessidade.
O prefixo de caminho e o root_path
A opção --root-path só entra em cena quando o proxy retira um prefixo da URL antes de chegar à API, como em /api/v1. No exemplo, a API responde na raiz do domínio, então não precisa dela. Guias antigos que definem o root_path dentro de FastAPI() estão defasados: esse parâmetro foi descontinuado depois da versão 0.145.0.
HTTPS com Certbot
O domínio precisa apontar para o IP da VPS, porque o certificado é emitido para o nome do domínio, e não para o IP. O Certbot também exige que o site esteja acessível na internet pela porta 80. Com o Nginx e o snap, as instruções do site do Certbot são:
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --nginx
O último comando obtém o certificado e edita a configuração do Nginx. Para apenas obter o certificado, use sudo certbot certonly --nginx. Os certificados do Let's Encrypt duram cerca de três meses, e os pacotes do Certbot trazem uma tarefa agendada ou um timer do systemd para renovar. Teste a renovação:
sudo certbot renew --dry-run
O HTTPS protege a conexão entre o visitante e o servidor, mas não substitui a autenticação da API: quem pode chamar cada rota continua sendo decisão do seu código.
Sequência completa
Um exemplo de ordem; confira cada passo no seu servidor:
- apontar
api.exemplo.com.brpara o IP da VPS; - conferir o Python (3.10 ou mais novo) e instalar o Nginx;
- criar o usuário, a pasta e o ambiente virtual;
- instalar o
fastapi[standard]e fixar as versões; - criar o arquivo de variáveis, com permissão restrita;
- testar o Uvicorn com
--host 127.0.0.1; - criar o
api.servicee ativar; - criar o bloco do Nginx, rodar
nginx -te recarregar; - rodar o Certbot e o
renew --dry-run; - decidir o que fazer com
/docse o esquema OpenAPI; - conferir a rota por HTTPS, o redirecionamento de barra final (de
/itemspara/items/, que deve manter ohttps) e o reinício da VPS.
Outros projetos na mesma VPS
Quem já publicou outro projeto Python pode comparar com o guia Django na VPS, que também usa Nginx na frente. Para um processo de fundo que precisa ficar rodando, como um robô, veja Bot em Python na VPS. E, se a sua API precisa de um banco, o guia Supabase na VPS mostra um caminho com Docker.
Dá para comparar os planos de VPS lado a lado? VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer a loja
Perguntas frequentes
Preciso do Gunicorn para publicar o FastAPI?
Não. O exemplo usa apenas o Uvicorn, que inicia os processos quando você usa --workers.
A documentação recomenda venv e pip?
Ela recomenda o uv. O fluxo com python -m venv e pip aparece como alternativa, e é o fluxo do exemplo.
Posso usar fastapi run atrás do Nginx?
O fastapi run escuta em 0.0.0.0, e por isso o exemplo usa o Uvicorn com --host 127.0.0.1. Se preferir o fastapi run, consulte as opções dele na documentação do FastAPI antes de expor a API.
O FastAPI já está na versão 1.0?
Não. Na data da publicação, a versão do PyPI é a 0.162.0, e a documentação avisa que versões abaixo da 1.0.0 podem trazer mudanças que quebram o código em atualizações MINOR.