# disnake: a Discord API wrapper that keeps the discord.py shape

> disnake is a Python wrapper for the Discord API with proper rate limit handling, type-safety measures, and a FastAPI-like slash command syntax, and it deliberately preserves the syntax and structure of discord.py 2.0. It does not follow semantic versioning, so the README tells you to pin the dependency to a minor version, and voice support is an optional extra rather than part of the default install.

**DisnakeDev/disnake** — An API wrapper for Discord written in Python.

- Repository: https://github.com/DisnakeDev/disnake
- Website: https://docs.disnake.dev
- Stars: 771 · Forks: 145
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/disnakedev-disnake

## discord.py's shape, pointed at Discord's current API

disnake is a modern, easy to use, feature-rich, and async-ready API wrapper for Discord written in Python. The project description is a Python wrapper for the Discord API, and the homepage is the documentation site at docs.disnake.dev.

The key decision is stated in a single line in the README, under the key features: the syntax and structure of discord.py 2.0 is preserved.

That is the whole proposition. discord.py is the dominant Python library for Discord bots, and it has a very large body of existing code, tutorials, and community knowledge built around a particular shape, a Bot class, a command decorator, an extension system, a context object. disnake keeps that shape and swaps out the layer underneath.

The three key features explain what the swap buys. Proper rate limit handling, because Discord's rate limits are per route and per bucket and getting them wrong is the classic cause of a bot that gets banned. Type-safety measures, which in a wrapper that mirrors a large external API matters, because the API has hundreds of fields and a typo in a keyword argument is otherwise a runtime error. And a FastAPI-like slash command syntax, which is the FastAPI style of declaring a command with a function signature and type hints, and the annotations on those parameters become the options Discord shows to the user.

The library is MIT licensed, the development status in the metadata is Production/Stable, the supported Python versions are 3.10 through 3.14, and the package is marked as typed. The repository is not archived and the last push was on 2026-10-20, with releases v2.12.2 from 2026-10-08, v2.12.1 from 2026-07-22, and v2.12.0 from 2026-02-21.

## Three command models, and a bot class for each

The examples in the README show the three ways you talk to a user, and they use three different bot classes, which is the first thing to understand about the API.

Slash commands use the interaction bot.

```python
import disnake
from disnake.ext import commands

bot = commands.InteractionBot(test_guilds=[12345])

@bot.slash_command()
async def ping(inter):
    await inter.response.send_message("Pong!")

bot.run("BOT_TOKEN")
```

The interaction bot is the one that can register slash commands, and the constructor takes a list of test guilds, which is how a command is registered immediately in a development guild rather than waiting for the global registration to propagate.

Context menus, the right click menu on a user or a message, use the same bot class with a different decorator.

```python
import disnake
from disnake.ext import commands

bot = commands.InteractionBot(test_guilds=[12345])

@bot.user_command()
async def avatar(inter, user):
    embed = disnake.Embed(title=str(user))
    embed.set_image(url=user.display_avatar.url)
    await inter.response.send_message(embed=embed)

bot.run("BOT_TOKEN")
```

Prefix commands, the older style triggered by typing a prefix, use the plain bot class.

```python
import disnake
from disnake.ext import commands

bot = commands.Bot(command_prefix=commands.when_mentioned)

@bot.command()
async def ping(ctx):
    await ctx.send("Pong!")

bot.run("BOT_TOKEN")
```

The prefix here is the when_mentioned helper, which means the command only fires when the bot is mentioned, and the handler takes a context object rather than an interaction.

The point of showing all three is that the library does not push you toward one interaction model. A bot can expose slash commands, context menus, and prefix commands at the same time, and a project migrating from an older library can keep its prefix commands while moving new features to slash commands.

## The versioning promise, and why you should pin

There is a paragraph in the README that is worth reading twice, because it is the sort of thing that saves a deployment.

The project does not quite follow semantic versioning, and the documentation links to a page on version guarantees for the details. To be on the safe side and avoid unexpected breaking changes, the README recommends pinning the dependency to a minor version, with the examples given being a wildcard on the minor, or a compatible release specifier, or an exact version.

That is an unusual instruction to find in a library README, and it is a direct consequence of a wrapper that mirrors a fast moving external API. A library that tracks Discord's API is going to be reshaped whenever Discord changes shape, and the maintainers are being straight about the fact that a minor version bump can carry breaking changes.

The practical effect is that the ecosystem rule people expect, that a compatible release specifier means no breaking changes, does not hold here. A requirements file with a caret or a tilde on the disnake version is not a promise.

The three named key features line up with this. Rate limit handling is a behaviour you depend on and cannot easily test for. Type-safety measures are the type hints on the request and response structures. And the FastAPI-like syntax for slash commands means the command signature is the declaration, so a change in how a parameter is declared changes the command the user sees in the Discord client, which is a user visible change rather than an internal one.

For an operator, the practical rule is the one the README gives. Pin the version, and read the changelog, which the project publishes at the documentation site and also keeps in a changelog directory in the repository.

## Three runtime dependencies, and two optional extras

The package metadata is short, and that is a deliberate design decision for a library that most people install into an application.

The runtime dependencies are three. aiohttp is the asynchronous HTTP client, pinned to the 3.x series. typing-extensions provides the typing helpers that back the type-safety claims. And yarl is the URL library, which aiohttp uses and which a wrapper that builds request URLs and parses response links needs directly.

There are no other runtime dependencies, and for a Discord wrapper that is worth noting, because a lot of the ergonomics people associate with a bot library come from other packages, and disnake implements them itself instead.

There are two optional dependency groups, and they are the interesting part of the metadata.

The speed group installs orjson for faster JSON handling, the aiohttp speedups extra, and backports.zstd for Python versions before 3.14. The conditional dependency on the Python version is a small sign of a project that tracks new interpreter releases closely, and the metadata comment about the classifiers needing to be sorted in the sequential order shows the same attention to detail.

The voice group installs PyNaCl for the cryptography the voice protocol needs, dave.py for the voice gateway, and audioop-lts on Python 3.13 and later. That last one is the interesting constraint, because audioop was removed from the standard library in Python 3.13, and the replacement package is only needed on the versions where it is gone.

The build itself is hatchling with versioningit, and the version is dynamic, derived from the source control tag by the versioning tool rather than written into the file. The release notes live in a changelog directory and are published to the documentation site, and there is a separate release document at the root of the repository.

## Voice is an extra, and Linux needs system packages

Voice support is the feature that most often decides whether a Discord library works for a project, and disnake treats it as an opt-in rather than a default.

Installing the library without full voice support is the plain install. Installing it with voice support means replacing the package name with the voice extra, and the README points at a section of the guide for the details of voice support and of installing the development version.

The system level requirement is spelled out, because it is the one that breaks installs. Voice support on Linux requires the libffi-dev and python-dev packages to be installed through your preferred package manager before running the install commands.

That is a sensible boundary. Voice support pulls in a cryptography library, a voice gateway client, and a standard library module that is no longer shipped with recent interpreters, and the cost of that is only paid by the projects that want voice.

The example directory in the repository shows the same division. There is a basic bot, a basic voice example, a components example for the newer message component API, converters, a custom context, an edit and delete example, a guessing game, a new member example, reaction roles, a reply example, a secret example, a user echo webhook example, a background task example, and directories for the interactions and for views.

The two extras, speed and voice, are a good summary of how the project thinks about itself. The core is the API wrapper with the ergonomics of discord.py, and everything that is not the API wrapper is optional.

## The repository, and the tooling around it

The repository layout is a mature Python library rather than a script, and the details of the tooling say how the project is maintained.

The library itself is in the disnake directory, with the documentation in docs, the examples in examples, the tests in tests, and a scripts directory. There is a changelog directory, a release document, a contributing guide, and a noxfile for the test sessions. The pre-commit configuration and a libcst codemod configuration are both present, which is a sign of a project that automates large scale edits across the codebase, and a readthedocs configuration is there for the documentation builds.

The presence of a codemod configuration is worth a moment, because it points at the nature of the work. A wrapper with a large generated and hand written surface gets refactored often, and a codemod is how you rename a parameter across hundreds of call sites without hand editing them.

The examples are the other interesting part, because a library that documents itself through a set of runnable examples is a library that assumes it will be used by people who learn by copying. The set covers the modern surfaces, slash commands through the interactions directory, message components, views, converters, and the background task pattern, and it includes a secret example, which suggests the maintainers expect people to be careless with tokens.

On the project itself, the README links the documentation, a guide, the Discord server, and the Discord developers server, and the release history shows a project that ships regularly, with the last three versions landing in February, July, and October 2026.

## Conclusion

disnake fits a Python team that wants to write Discord bots with slash commands and modern interaction APIs without giving up the ergonomics of discord.py, especially a team that already has discord.py code and wants to move without rewriting it. It does not fit a team that wants dependency ranges to mean what semantic versioning says, because the project states that it does not quite follow it. Verify first that the features you need exist in the current version, since the API surface is what moves, that you have pinned the dependency to a minor or exact version as the README recommends, and that you have the system libraries voice support needs on Linux before you enable that extra.

## FAQ

### What is disnake and how does it relate to discord.py?

It is a Python wrapper for the Discord API whose syntax and structure preserve those of discord.py 2.0. The key features listed are proper rate limit handling, type-safety measures, and a FastAPI-like slash command syntax.

### How do I install disnake?

Python 3.10 or higher is required, and the install is python3 -m pip install -U disnake on Linux and macOS, or py -3 -m pip install -U disnake on Windows. For voice support, install the voice extra instead, and on Linux that needs the libffi-dev and python-dev system packages first.

### Does disnake follow semantic versioning?

No, not quite, and the README says so. To avoid unexpected breaking changes it recommends pinning the dependency to a minor version such as a wildcard on the minor, or to an exact version, and the project publishes version guarantees in its documentation.

### Which bot classes does disnake provide?

The examples show the interaction bot for slash commands and context menus, constructed with a list of test guilds so commands register immediately in a development guild, and the plain bot for prefix commands, where the handler receives a context object rather than an interaction.

### What are the runtime dependencies of disnake?

Three: aiohttp for the asynchronous HTTP client, typing-extensions for the typing helpers, and yarl for URL handling. There are two optional extras, speed, which adds orjson and the aiohttp speedups, and voice, which adds PyNaCl, dave.py, and audioop-lts on Python 3.13 and later.

## Sources

- [DisnakeDev/disnake on GitHub](https://github.com/DisnakeDev/disnake)
- [License: MIT](https://github.com/DisnakeDev/disnake/blob/master/LICENSE)
- [Project website](https://docs.disnake.dev)
- [README](https://github.com/DisnakeDev/disnake/blob/master/README.md)
- [Releases](https://github.com/DisnakeDev/disnake/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/disnakedev-disnake