An HTTP-first Python library for Discord bots, running on HTTP interactions, the gateway, or both, with full cache control.
- Runs over HTTP, the gateway or both, the library detects which on boot.
- Nothing is cached unless you ask for it, and what is cached is stored compactly, even in thousands of servers.
- Act on anything by ID without fetching it first.
- Offline mode for scripts and cron jobs, use the API without running a bot at all.
- Plain Python types like
str,intanddatetime, with builders only where it is genuinely complex, like embeds or components. - Supports guild and user installs, fully type-hinted and kept in sync with the Discord API.
- Small, deliberate dependency set, every dependency has to earn its place.
- Familiar API for anyone coming from discord.py, so there is little to relearn.
Requirements
- Python 3.11 to 3.14
- Recommended: a public HTTPS endpoint for Discord to send interactions to, usually a reverse proxy (nginx, apache2, etc.) in front of your bot. Without one, interactions arrive over the gateway instead, see connection modes below.
Installing
Install with pip install discord.http (or python -m pip install discord.http if pip is not on your path).
Connection modes
On boot, the library picks a mode from your bot's Interactions Endpoint URL and the intents you pass, and logs it.
| Mode | Interactions | Gateway events | When |
|---|---|---|---|
HTTP |
Over HTTP | No | Endpoint URL set |
HTTP+WS |
Over HTTP | Yes | Endpoint URL set, with intents |
WS |
Over the gateway | No | No endpoint URL, or disable_http_server=True |
WS+ |
Over the gateway | Yes | Same as WS, with intents |
The HTTP server runs in every mode unless disable_http_server=True is passed. With that flag and an endpoint URL still set, Discord keeps sending interactions to the URL, so this bot only handles gateway events.
Quick example
from discord_http import Context, Client
client = Client(
token="Your bot token here"
)
@client.command()
async def ping(ctx: Context):
""" A simple ping command """
return ctx.response.send_message("Pong!")
client.start()
With the gateway
Want to also listen to gateway events? Pass your desired intents to the client, which starts the gateway.
from discord_http import Client, Message
from discord_http.gateway import Intents
client = Client(
token="Your bot token here",
intents=Intents.guild_messages
)
@client.listener()
async def on_message_create(msg: Message):
print(f"{msg.author} sent a message in {msg.channel}")
client.start()
Offline mode
Not every job needs a running bot. offline_run() logs in, runs your function once and exits, with no HTTP server, no gateway connection and no public endpoint needed. Great for cron jobs, one-off scripts and admin tools.
from discord_http import Client
client = Client(
token="Your bot token here"
)
async def main():
channel = client.get_partial_channel(123456789012345678)
await channel.send("Nightly backup finished!")
client.offline_run(main)
Need help with hosting or the endpoint URL? See the getting started guide.
Contributing
Contributions are welcome! Have a look at the contributing guide and the style guide before opening a pull request.
Automated tests use Python's built-in unittest module, run them from the project root with:
make test- or
python -m unittest discover -s tests -p "test_*.py"
Resources
1 maintainer
Metadata
1 maintainer
Release files for discord.http 3.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| discord_http-3.3.0.tar.gz | 309.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| discord_http-3.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 568.1 kB
Release files / discord_http-3.3.0.tar.gz
| Download URL | discord_http-3.3.0.tar.gz |
|---|---|
| Size | 309.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87920f25d1019cede627b3b70a1390b9ab00316ca01e01d447dd9127d890e734
|
|
BLAKE2b-256 checksum How to use checksums |
22aa16b9701ad66f540bac0635f97505956c7b4937496464e0477704d8620704
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / discord_http-3.3.0-py3-none-any.whl
| Download URL | discord_http-3.3.0-py3-none-any.whl |
|---|---|
| Size | 258.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
54f7daef6930b648ce529ee1e864ac435f91612db3b1a81d6b81cbf6203aac60
|
|
BLAKE2b-256 checksum How to use checksums |
dd24b59bb5f8a530a26e51e7e945c750fe1e475eceec3c66a1921afd0cd16e9f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.9 {"installer":{"name":"uv","version":"0.9.9"},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
