Nextcord: a maintained fork of discord.py for the Discord API

A fork, and what the README claims for it

Nextcord is a modern, easy-to-use, feature-rich and async-ready API wrapper for Discord written in Python, and the package description is more direct about its lineage: a Python wrapper for the Discord API forked from discord.py.

The three key features the README lists are a modern Pythonic API using `async` and `await`, proper rate limit handling, and being optimised in both speed and memory.

The rate limit claim is the one worth pausing on. Discord's API applies per-route limits, and the standard approach is to read the response headers, work out when the bucket resets, and sleep. A wrapper that does that properly removes a class of bug where a bot bursts through a route and gets itself rate limited, or where the sleeping logic blocks the wrong task. Doing it in the wrapper rather than in each bot is the right place for it.

The repository metadata gives the package details. The name on PyPI is `nextcord`, the licence is MIT, the documentation is at docs.nextcord.dev, and the classifiers describe the project as Development Status 5, Production/Stable, with a Framework of AsyncIO and aiohttp, and Typing Typed. The typing classifier is worth noting, because a typed API is a large part of what makes a wrapper pleasant to use with an editor.

The project is not archived and the last push was on 2026-10-12. The release history is v3.2.0 from 2026-05-21, v3.1.1 from 2025-08-16 and v3.1.0 from 2025-04-18, and the default branch is master.

Four ways to install, and the extras that matter

Python 3.12 or higher is required, and the README then gives four installation variants, which is a sign that the optional pieces are genuinely optional rather than bundled.

The plain install, for Linux and macOS, is `python3 -m pip install -U nextcord`, and on Windows it is `py -3 -m pip install -U nextcord`.

For voice support, the Linux and macOS form is `python3 -m pip install -U "nextcord[voice]"` and the Windows form is `py -3 -m pip install -U nextcord[voice]`.

For the speedup packages, the Linux and macOS form is `python3 -m pip install -U "nextcord[speed]"` and the Windows form is `py -3 -m pip install -U nextcord[speed]`.

And for the development version, it is a clone and a local install with the voice extra: `git clone https://github.com/nextcord/nextcord/`, then `cd nextcord`, then `python3 -m pip install -U .[voice]`.

The optional packages section then names what is actually behind those extras. PyNaCl at 1.5.0 or newer is for voice support. aiodns, Brotli and cchardet are for aiohttp speedup. orjson is for json speedup.

The Linux caveat is the one that bites. On Linux, installing voice requires the system packages libffi-dev, or libffi-devel on some systems, and python-dev, for example python3.12-dev for Python 3.12, to be installed with the system package manager before running the pip commands. A native build dependency in a pip install is exactly the kind of thing that works on a developer laptop and fails in a Docker build, and the README calls it out before you hit it.

The four-line bot, and the slash command model

The quick example is short enough that it explains the whole API shape.

import nextcord
from nextcord.ext import commands


bot = commands.Bot()

@bot.slash_command(description="Replies with pong!")
async def ping(interaction: nextcord.Interaction):
    await interaction.send("Pong!", ephemeral=True)

bot.run("token")

Two things stand out. The decorator is `slash_command`, so the command is registered as an application command rather than as a prefixed text command, and the callback receives an `Interaction` rather than a message and a context. And the reply is `ephemeral`, so it is visible only to the person who ran it.

That is the modern Discord command model, and it is the one that needs the slash command registration round trip, the permission model and the interaction responses. The wrapper hides most of that behind a decorator and an `await interaction.send`.

The `commands.Bot` name is the same as in discord.py, and that is the point of the fork: a bot written against one is a bot written against the other, with the import path changed.

The README then adds the security note that matters most in a bot codebase: it is not advised to leave your token directly in your code, as it allows anyone with it to access your bot, and if you intend to make your code public you should store it securely, with a link to an example in the repository for doing it.

The examples directory is the feature list

The examples directory is where the library's capabilities are visible.

The core ones are the usual: `basic_bot.py`, `basic_voice.py`, `background_task.py` and `background_task_asyncio.py`, `guessing_game.py`, `head_or_tails.py`, `new_member.py`, `reaction_roles.py`, `reply.py`, `edits.py` and `deleted.py`, `webhook.py`, and `secret.py`.

The Discord-specific surfaces have their own directories. There is `examples/views/` for interactive components, `examples/modals/` for modal dialogs, and `examples/application_commands/` for the slash command registration flow, which is the one you will need to read if you are setting up a new bot with application commands.

Two examples are about the extension machinery rather than about Discord. `custom_context.py` and `custom_interaction.py` show how to subclass the context and the interaction objects, which is how you add your own state to the command layer, and `converters.py` is about type conversion for command arguments.

And then there is `secure_token_storage.py`, which is referenced from the README's security note. Having a worked example of token storage in the repository, next to the warning, is a detail that says the maintainers expect people to publish bot code, and they would rather that code not leak a token.

The repository root also has a `docs/` directory and a `scripts/` directory, a `MANIFEST.in`, a `CONTRIBUTING.md` and a `task.env` file.

How the fork is built, and the codemod file

The `pyproject.toml` uses Poetry, and the version field is a placeholder of 0.0.0, modified by dynamic versioning. That is a common pattern for a library with tags: the version in the published artefact comes from the tag rather than from a file that has to be edited.

The package list is explicit about the module structure, and it is a useful map of the library. There is the `nextcord` package itself, a `nextcord.types` package, a `nextcord.ui` package with a `nextcord.ui.select` subpackage, a `nextcord.webhook` package, and four extension packages: `nextcord.ext.application_checks`, `nextcord.ext.commands`, `nextcord.ext.slash_utils` and `nextcord.ext.tasks`.

The `ui` and `ui.select` packages are the interactive components, the `types` package is the typing layer, and the four `ext` packages are the framework pieces: commands, slash command helpers, the application checks used to validate command registration, and the background task helper that the two background task examples use.

The core dependencies are small. aiohttp at 3.8 or newer, typing_extensions at 4.2 or newer, and audioop-lts for Python 3.13 and newer, which is the backport of the `audioop` module that was removed from the standard library in Python 3.13. That single conditional dependency tells you the project tracks the standard library removals, which is a maintenance signal.

PyNaCl and orjson are optional dependencies, with a comment in the manifest explaining that there is currently no way to express passthrough extras in Poetry, and links to the Poetry issue and to the aiohttp setup file, with the speedup extra commented out in the manifest.

The root also has a `.libcst.codemod.yaml` file, which is the configuration for a libcst code transformation. A project ships one of those when it wants existing code rewritten automatically, which fits a fork whose whole purpose is to be adopted in place of another library, and it is worth asking the maintainers what the codemod covers before you plan a migration by hand.

Where Nextcord is the wrong choice

The first wrong case is a team that has standardised on the upstream library and has no reason to move. A fork is a permanent dependency decision, because every upstream security fix and every new Discord feature has to be checked against the fork, and the fork's release cadence is a second thing to track. If your bot works on discord.py and there is no feature gap, moving is cost with no return.

The second is a bot that does not need voice, and does not care about the speedups. The `voice` extra pulls in PyNaCl and, on Linux, system build packages, which means a native build step in your deployment for a feature you are not using. Installing the plain package and the plain package only is the correct choice there, and the README makes that easy enough.

The third is a codebase that has to run on Python below 3.12. The library requires 3.12 or higher, and a service pinned to 3.10 is out of luck.

The fourth is a project that treats the Discord library as a commodity and wants the one with the largest community behind it, in the sense of the people who can answer a question about it. A fork has its own Discord server and its own documentation.

The fifth is a bot that needs a feature the fork has not yet implemented. That is the fundamental risk of a fork, and the way to manage it is to check the fork's own issue tracker and changelog before you commit to it, rather than after.

Editorial conclusion

Nextcord suits a Python team that wants to write a Discord bot with an async API and either needs the fork's newer Discord features or wants a project that is not waiting on the upstream, and that is comfortable with the discipline of tracking a fork. It does not suit a team that has decided that the upstream library is the only acceptable dependency, and it does not suit a bot that does not need anything the fork adds, since you gain the fork's release cadence and the upstream's feature set at once. Before adopting it, read the `docs/` directory and the examples for the features you actually plan to use, and check the `python` constraint of `^3.12`, because the library refuses to install on anything older.

Frequently asked questions

Official sources

1. License: MIT
2. nextcord/nextcord on GitHub
3. Project website
4. README
5. Releases