Discord API (discord.py)

2.7.1 · active · verified Tue Mar 17

Community-maintained Python wrapper for the Discord API. Current version is 2.7.1 (Mar 2026). PyPI package is 'discord.py' (with dot), imports as 'discord'. Note: 'pip install discord' installs a mirror stub that redirects to discord.py — always install discord.py directly. The library was abandoned in 2021 and resumed in 2022 with a full v2 rewrite; vast amounts of pre-v2 tutorial code is broken.

Warnings

breaking discord.py was abandoned Aug 2021 and resumed Aug 2022 with v2.0 — a near-complete rewrite. Any tutorial or code from 2021 or earlier is likely broken. v1.x and v2.x are not API-compatible.
Fix: Check discord.py version first. Migrate using the official v2 migration guide at discordpy.readthedocs.io/en/stable/migrating.html
breaking Intents are mandatory in v2. Client() and Bot() constructors require an intents= argument. Omitting it raises: 'TypeError: __init__() missing 1 required keyword argument: intents'.
Fix: intents = discord.Intents.default(); bot = commands.Bot(command_prefix='!', intents=intents)
breaking message_content is a Privileged Intent since Sep 2022. Without it, message.content is always empty string. Prefix commands silently stop working. Must be enabled BOTH in Developer Portal AND in code.
Fix: In code: intents.message_content = True. In Discord Developer Portal: Bot → Privileged Gateway Intents → Message Content Intent → toggle ON.
breaking Slash commands (app commands) are not available via the old @bot.command() decorator. They require discord.app_commands.CommandTree or the @bot.tree.command() decorator introduced in v2.
Fix: Use @bot.tree.command() for slash commands. Call await bot.tree.sync() to register them with Discord.
breaking client.run() is synchronous and blocks. Do not wrap it in asyncio.run() — this causes RuntimeError: This event loop is already running.
Fix: Call bot.run('token') directly at the top level, not inside an async function. Use async with bot: / await bot.start('token') if you need async entry point.
gotcha pip install discord installs a mirror stub package that just re-exports discord.py. It may lag behind the real package version. Always install discord.py explicitly.
Fix: pip install discord.py (not pip install discord)
gotcha Privileged Intents (message_content, members, presences) require Discord Developer Portal approval for bots in 100+ servers. Enabling in code alone is insufficient — the bot will connect but receive empty data silently.
Fix: Developer Portal → Your App → Bot → Privileged Gateway Intents. Enable each required intent. For bots under 100 servers, toggle is sufficient. For 100+ servers, apply for verification.
gotcha Third-party slash command libraries (discord-py-slash-command, discord-interactions) were built for v1.x. They conflict with v2.x which has native app_commands support. Remove them before upgrading.
Fix: pip uninstall discord-py-slash-command discord-interactions. Use discord.app_commands natively in v2.

Install

pip install discord.py Python (core)
pip install "discord.py[voice]" Python (with voice support)

Imports

discord
```
import discord
from discord.ext import commands
```
Package installs as discord.py but imports as discord. 'import discord.py' is a SyntaxError. 'pip install discord' installs a mirror stub — always pip install discord.py.

Quickstart

Minimal prefix command bot with required intents declaration (v2.x).

import discord
from discord.ext import commands

# Intents are REQUIRED in v2 — no defaults silently work
intents = discord.Intents.default()
intents.message_content = True  # privileged intent — must enable in Dev Portal too

bot = commands.Bot(command_prefix='!', intents=intents)

@bot.command()
async def ping(ctx):
    await ctx.send('pong')

bot.run('YOUR_BOT_TOKEN')

view raw JSON →