discord.py — Python Wrapper for the Discord API

Introduction

discord.py is an async Python library that wraps the Discord API, giving Python developers a clean, Pythonic way to build bots. It leverages asyncio for non-blocking I/O and covers the entire Discord API surface including slash commands, message components, and voice.

What discord.py Does

• Provides an async/await interface to every Discord REST endpoint and gateway event
• Supports application commands (slash commands, context menus) via the app_commands module
• Handles automatic rate limiting, connection management, and reconnection
• Includes UI components: buttons, select menus, modals, and text inputs
• Offers voice support through the optional PyNaCl and FFmpeg dependencies

Architecture Overview

discord.py uses aiohttp under the hood for both WebSocket gateway connections and REST API calls. The library maintains an internal state cache of guilds, channels, members, and messages. Event dispatching follows a decorator-based pattern where you register callbacks on a Bot or Client instance. The commands extension (ext.commands) adds a framework for prefix-based commands with argument parsing, while app_commands handles Discord's interaction-based slash commands.

Self-Hosting & Configuration

• Requires Python 3.8 or newer
• Install with pip install discord.py (add [voice] extra for voice support)
• Create a bot at the Discord Developer Portal and copy the token
• Enable required privileged gateway intents (Message Content, Server Members) if needed
• Run as a long-lived process on any server, or containerize with Docker

Key Features

• Native async/await design built on asyncio
• ext.commands framework with cogs for modular bot organization
• Full support for Discord's interaction-based UI (buttons, modals, select menus)
• Automatic sharding for large-scale bots
• Extensive documentation and a large community of third-party extensions

Comparison with Similar Tools

• Discord.js — JavaScript equivalent; discord.py is preferred by Python developers
• Pycord — Community fork of discord.py that added features during the library's hiatus
• Nextcord — Another fork; discord.py's return to active development reduced the need for forks
• hikari — Alternative async Python Discord library with a more modular architecture
• disnake — Fork focused on early slash command support; discord.py now covers the same features natively

FAQ

Q: Is discord.py still maintained? A: Yes. After a period of inactivity, the creator resumed development and the library is actively updated.

Q: How do I add slash commands? A: Use the app_commands module: decorate functions with @app_commands.command() and sync them with tree.sync().

Q: Can discord.py handle multiple servers at scale? A: Yes. Use AutoShardedClient to automatically split the gateway connection across shards for bots in many guilds.

Q: What license does discord.py use? A: MIT License.

Sources

• https://github.com/Rapptz/discord.py
• https://discordpy.readthedocs.io