Como hospedar um bot do Discord em Python

Um bot feito com discord.py é um script Python que abre uma conexão com o Gateway do Discord e fica rodando. Hospedar o bot é decidir onde esse processo vive, para que ele continue ativo quando você fechar o editor ou desligar o computador.

Este guia cobre o caminho inteiro: o código, as dependências, o token, o deploy e a verificação. Os exemplos usam a API do discord.py 2.x; confira a versão atual no PyPI.

O que você precisa antes de hospedar?#

• Uma versão do Python ainda com suporte. A documentação do discord.py informa o mínimo exigido. Prefira uma versão atual.
• Uma aplicação no Discord Developer Portal, com o bot criado e o token copiado.
• O bot convidado para o seu servidor de testes.
• Um lugar para o processo rodar 24 horas. Se ainda está comparando opções, veja como deixar um bot do Discord online 24/7 e quanto custa hospedar um bot do Discord.

Como escrever um bot discord.py que roda em produção?#

Crie um ambiente virtual e instale a biblioteca:

python3 -m venv .venv
source .venv/bin/activate   # no Windows: .venv\Scripts\activate
pip install -U discord.py

Agora o bot.py (discord.py 2.x). Ele usa um slash command, que não exige o intent privilegiado message_content, e lê o token do ambiente:

import os

import discord
from discord.ext import commands


class MeuBot(commands.Bot):
    async def setup_hook(self) -> None:
        # Registra os slash commands no Discord ao iniciar
        await self.tree.sync()


intents = discord.Intents.default()
bot = MeuBot(command_prefix=commands.when_mentioned, intents=intents)


@bot.event
async def on_ready() -> None:
    print(f"Online como {bot.user}")


@bot.tree.command(name="ping", description="Mostra a latência do bot")
async def ping(interaction: discord.Interaction) -> None:
    await interaction.response.send_message(f"Pong! {round(bot.latency * 1000)} ms")


bot.run(os.environ["DISCORD_TOKEN"])

Dois detalhes importam para a hospedagem. Primeiro, os.environ["DISCORD_TOKEN"] falha com KeyError se a variável não existir, o que é bom: o bot nem sobe com configuração incompleta. Segundo, bot.run() já configura o log e bloqueia até o processo terminar, então não precisa de laço nem de asyncio.run.

Sincronizar os comandos a cada inicialização funciona para um bot pequeno. Se você reinicia o bot com frequência, rode a sincronização só quando os comandos mudarem.

Quando preciso do intent message_content?#

Só se o bot lê o texto das mensagens, como em comandos com prefixo (!ping). O quickstart do discord.py, que responde a $hello, avisa num comentário que o exemplo "requer o intent message_content" e o habilita com intents.message_content = True. Esse é um intent privilegiado: ligue-o na aba Bot do Developer Portal, em Privileged Gateway Intents, e também no código. Ligar só em um dos lados não basta. Acima de 100 servidores, a documentação avisa que o uso de intents privilegiados exige verificação do bot.

Como declarar as dependências?#

A hospedagem precisa saber o que instalar. Crie um requirements.txt na raiz do projeto, ao lado do bot.py:

discord.py>=2.7,<3

Se o bot toca áudio em canal de voz, a documentação indica instalar o extra: discord.py[voice]. Para qualquer outra biblioteca que você usar (banco de dados, requisições HTTP), fixe a versão do mesmo jeito. Gere a lista do seu ambiente com pip freeze > requirements.txt quando tudo estiver funcionando.

Como passar o token sem colocá-lo no código?#

Use uma variável de ambiente. No terminal, em Linux e macOS:

export DISCORD_TOKEN="cole_o_token_aqui"
python3 bot.py

No PowerShell: $env:DISCORD_TOKEN="cole_o_token_aqui". Se você usa um arquivo .env localmente, nunca o envie para o repositório: coloque-o no .gitignore. O conceito, e por que ele existe, está em o que são variáveis de ambiente. Se o token vazar, redefina-o no Developer Portal; o antigo deixa de funcionar na hora.

Como colocar o bot no ar?#

Em qualquer hospedagem, o roteiro é o mesmo: enviar bot.py e requirements.txt, definir DISCORD_TOKEN e iniciar com python bot.py. O que muda é quem mantém o processo vivo:

Num VPS, rode o bot sob systemd com Restart=always ou num container Docker com --restart unless-stopped, como mostra o guia de bot online 24/7. Rodar python bot.py numa sessão SSH não serve: o processo morre quando a sessão fecha. Para entender o que acontece com o PC, leia bot offline quando o PC desliga. A ideia geral de enviar o código para rodar em outra máquina está em o que é deploy.

Como verificar que o bot está funcionando?#

1. Veja os logs de inicialização. Você deve ler a linha Online como NomeDoBot.
2. No servidor, confira se o bot aparece como online na lista de membros.
3. Digite /ping e confirme a resposta. Os slash commands podem levar alguns instantes para aparecer; se não aparecerem, reinicie o cliente do Discord.
4. Mate o processo e veja se a hospedagem o reinicia sozinha. Sem isso, o "24/7" é só otimismo.

Quais erros comuns derrubam um bot discord.py?#

• discord.errors.LoginFailure: Improper token has been passed. O token está errado, com espaços sobrando ou foi redefinido. Copie de novo no Developer Portal e confira a variável.
• discord.errors.PrivilegedIntentsRequired. O código pede um intent privilegiado (como message_content) que não está ligado no portal. Ligue-o ou remova do código.
• ModuleNotFoundError: No module named 'discord'. As dependências não foram instaladas no ambiente onde o bot roda. Confira o requirements.txt.
• KeyError: 'DISCORD_TOKEN'. A variável não foi definida na hospedagem.
• Arquivo chamado discord.py. A documentação alerta: não nomeie seu script discord.py, pois ele conflita com a biblioteca. Use bot.py.
• Bot que cai com pouca RAM. O processo é morto quando a memória acaba. Veja a lista completa em por que o bot do Discord fica offline.
• Respostas lentas ou falhas por excesso de requisições. Veja o erro 429 do Discord.

Como fazer isso na Square Cloud#

Na Square Cloud, o seu bot.py roda num container isolado com o runtime Python, sempre ligado e sem modo de suspensão. O reinício automático vem ligado no deploy pelo painel e traz o bot de volta quando o processo encerra com erro. Você mesmo faz o deploy: upload de ZIP no painel, CLI, GitHub (push faz deploy) ou extensão do VS Code. No start, a plataforma instala as dependências com pip install -r requirements.txt. O discord.py funciona como qualquer outra biblioteca de Gateway, com sharding e voz, e o FFmpeg está disponível no container.

O token entra como variável de ambiente da aplicação, no painel, na API ou na CLI; a mudança vale no próximo restart, sem rebuild. O arquivo de configuração squarecloud.app é opcional: o painel o gera no deploy com runtime, memória e arquivo principal, e escrever o arquivo na raiz do projeto é a alternativa. Os logs aparecem em tempo real no painel, na CLI e no app de celular.

Todos os planos são pagos e cobrados em reais. O Hobby custa R$ 12,49 por mês, com 1 GB de RAM compartilhado entre as suas aplicações e mínimo de 256 MB por aplicação de fundo, como um bot. Veja os detalhes em hospedagem de bots do Discord.