A fully typed Discord API library for Python, built for bots that grow. It keeps the names you know
from discord.py (commands.Bot, interaction.response.send_message, ui.View, tree.sync()) and
fixes what makes discord.py painful once a bot gets big.
discord.py is a good library for a bot in a few servers. Shoal is for bots that keep growing, and it is just as easy for the small ones.
discord.py identifies its shards one after another, about five seconds apart, and ignores the
max_concurrency Discord gives large bots. Shoal identifies max_concurrency shards at a time, as
Discord documents. At 512 shards with a concurrency of 16, that is under three minutes instead of
about 43.
- Sessions survive restarts. discord.py keeps the session only in memory, so every restart identifies every shard again, and Discord sends every guild again. Shoal saves sessions (to files, or Redis) and resumes them on the next start.
- The cache survives restarts. Shoal restores the cache from a snapshot, marked stale until Discord confirms each entry, so the bot answers from a warm cache from the first second.
- A failed resume still resumes. discord.py falls back to the main gateway only when the resume URL answers with a 5xx, and then starts a new session. Shoal falls back on any failure (a timeout, a 5xx, an early close) and resumes there, as Discord recommends.
- Change shard counts without downtime.
bot.reshard(new_count)connects the new shards beside the running ones and switches over once they are all ready. discord.py has no way to do this short of a restart.
discord.py leaves IPC to you. Shoal includes it:
- Gateway and workers. One process holds the shards and streams events (
shoal.ipc, over TCP or a Unix socket, or through a Redis stream). Workers run your commands and can restart as often as you deploy. - Clusters. Several processes or hosts run one bot through Redis. They share one identify limiter, the REST rate limits, sessions, a directory of every shard, a command router (join a voice channel from any cluster) and the cache.
- A REST proxy. One process holds the token and the rate limits for all the others.
- Discord bans an IP for 10,000 invalid requests in 10 minutes. discord.py does not count them. Shoal counts the 401, 403 and 429 responses Discord counts, and holds requests back before the limit.
- After a 401 (a revoked token), discord.py keeps sending requests that fail. Shoal stops at the first one.
- Prometheus metrics for gateway events and latency per shard, REST requests and rate limits by route, the cache, IPC, voice and event loop health. discord.py has none.
- A blocked event loop is caught as it happens. discord.py warns once the heartbeat has been
stuck for 10 seconds, and again every 10 seconds after. Shoal's watchdog
(
async with LoopMonitor():) reports blocks over 0.25 seconds (configurable), names the line of your code that is blocking while it blocks, logs how long it lasted, and records it in metrics. - Late events are noticed. Shoal measures how long each message and interaction took to arrive, and warns when they arrive more than five seconds late: the sign that events queue up before your code sees them.
- Strict pyright and mypy over the library and its tests, with
Anybanned. - Every type and endpoint links to its section of Discord's docs, and CI checks the links. Every HTTP endpoint Discord documents and every gateway event is covered, as the coverage page, generated from Discord's docs, shows.
- A field that is absent and a field that is
nullstay different (UNSETandNone), so an edit can tell "leave it" from "clear it". discord.py turns most of them intoNone. - When Discord adds an enum value, Shoal decodes it as a real member of the enum, with its value
kept. discord.py makes an
unknown_<value>stand-in that is not a member. - REST is public and standalone:
RestClientcovers every endpoint asrest.<resource>.<verb>, with bot or OAuth2 bearer tokens, for workers and dashboards. discord.py'sClient.httpis internal and undocumented.
- Slash, prefix and hybrid commands, cogs and extensions, views, modals and Components V2 layouts.
- Interactions over the gateway, or over HTTP with no gateway at all (signed, verified endpoint). discord.py only has the gateway.
- Voice: play and listen, end-to-end encrypted (DAVE), as Opus packets or decoded PCM per user (decoding needs libopus). discord.py can play, but receiving audio takes a third-party extension.
- Voice messages, polls, the application's own emojis synced from a folder, and member chunking as
guilds arrive (
chunk_guilds_at_startup). - A cache with a policy per entity (size, TTL, whether to snapshot, which fields to keep), instead of one fixed cache.
- Loops (
tasks.loop) and a scheduler for reminders and cron jobs that survive restarts with Redis, without a sleeping task per job.
Coming from discord.py?
import shoal.compat as discordgives you the old names, so a bot can move file by file. See the compat example and the migration guide.
Shoal needs Python 3.12 or newer:
pip install shoal # the core
pip install "shoal[voice]" # join voice channels, play and listen
pip install "shoal[redis]" # share limits, sessions, cache, events and shards across processes
pip install "shoal[prometheus]" # Prometheus metrics
pip install "shoal[interactions]" # receive interactions over HTTP, without a gateway
pip install "shoal[zstd]" # zstd gateway compression on Python 3.12 and 3.13
pip install "shoal[all]" # everything aboveTo work on Shoal itself, install it from a clone with pip install -e ".[all]".
Each extra adds a dependency only some bots need, so the core install stays small.
import os
import shoal
from shoal import commands
bot = commands.Bot("!", intents=shoal.Intents.default().with_flags(message_content=True))
@bot.hybrid_command(description="Say hello")
async def hello(ctx: commands.Context, who: shoal.Member | None = None) -> None:
await ctx.send(f"Hello {(who or ctx.author).mention}!")
bot.run(os.environ["DISCORD_TOKEN"])!hello and /hello both work (sync the slash command once with await bot.tree.sync()).
29 runnable bots, each with its own README and each run against Discord, from the smallest bot to role menus, tickets, music and a big bot with Prometheus, Grafana, warm restarts and resharding, plus clusters and workers.
- Guides: writing a bot, commands and interactions, caching and restarts, scaling, sharding and IPC, voice, loops and scheduled jobs, dashboards and REST, metrics and Grafana, diagnosing a slow bot, architecture, migrating from discord.py.
- The API reference is generated from the docstrings:
uv run --group docs mkdocs serve. - Discord API coverage lists every endpoint Discord documents and the Shoal method for it, generated from Discord's docs and checked weekly.
- The roadmap says what is built and what is planned.
- Every module with behaviour has a test module, and coverage is held above 95%.
tests/conventions.pyenforces the project's rules across the whole tree: docs links, ordering, constants defined once, slots, exports, test layout.- CI runs on Python 3.12, 3.13 and 3.14, on Linux, Windows and macOS.
See CONTRIBUTING.md for the rules, the layout and every check CI runs.