0
# Nextcord
1

2
A modern, comprehensive Python library that provides an async-ready API wrapper for Discord's bot API, forked from discord.py. It offers a feature-rich, Pythonic interface for building Discord bots with support for slash commands, message components, auto-moderation, voice capabilities, and proper rate limiting.
3

4
## Package Information
5

6
- **Package Name**: nextcord
7
- **Language**: Python
8
- **Installation**: `pip install nextcord`
9
- **Voice Support**: `pip install nextcord[voice]`
10
- **Speed Optimization**: `pip install nextcord[speed]`
11

12
## Core Imports
13

14
```python
15
import nextcord
16
```
17

18
Common imports for bot development:
19

20
```python
21
from nextcord import Client, Intents, Activity, ActivityType, Status
22
from nextcord.ext import commands
23
```
24

25
For UI components:
26

27
```python
28
from nextcord.ui import View, Button, Select, Modal, TextInput
29
```
30

31
For background tasks:
32

33
```python
34
from nextcord.ext import tasks
35
```
36

37
## Basic Usage
38

39
### Simple Bot with Client
40

41
```python
42
import nextcord
43
from nextcord.ext import commands
44

45
# Create bot with command prefix
46
bot = commands.Bot(command_prefix='!', intents=nextcord.Intents.default())
47

48
@bot.event
49
async def on_ready():
50
    print(f'{bot.user} has connected to Discord!')
51

52
@bot.command(name='hello')
53
async def hello(ctx):
54
    await ctx.send(f'Hello {ctx.author.mention}!')
55

56
# Run the bot
57
bot.run('YOUR_BOT_TOKEN')
58
```
59

60
### Slash Commands
61

62
```python
63
@bot.slash_command(description="Say hello to someone")
64
async def hello(interaction: nextcord.Interaction, user: nextcord.Member):
65
    await interaction.response.send_message(f'Hello {user.mention}!')
66
```
67

68
### UI Components
69

70
```python
71
from nextcord.ui import View, Button
72

73
class MyView(View):
74
    @nextcord.ui.button(label='Click me!', style=nextcord.ButtonStyle.primary)
75
    async def button_callback(self, button, interaction):
76
        await interaction.response.send_message('Button clicked!', ephemeral=True)
77

78
@bot.slash_command()
79
async def ui_demo(interaction: nextcord.Interaction):
80
    view = MyView()
81
    await interaction.response.send_message('Here is a button:', view=view)
82
```
83

84
## Architecture
85

86
Nextcord follows a hierarchical architecture centered around the Discord API structure:
87

88
- **Client/Bot**: Central connection and event management
89
- **Guilds (Servers)**: Server containers with members, channels, and roles
90
- **Channels**: Communication endpoints (text, voice, stage, threads)
91
- **Users/Members**: User representations with guild-specific attributes
92
- **Messages**: Content delivery with embeds, attachments, and components
93
- **Interactions**: Modern Discord features (slash commands, buttons, modals)
94
- **Extensions**: Modular functionality (commands framework, tasks, checks)
95

96
The async/await pattern provides efficient concurrent handling of Discord events and API calls, while the cog system enables organized, modular bot architecture.
97

98
## Capabilities
99

100
### Client and Connection Management
101

102
Core client classes for connecting to Discord, managing bot lifecycle, handling events, and maintaining connections with proper sharding support for large bots.
103

104
```python { .api }
105
class Client:
106
    def __init__(self, *, intents: Intents, **options): ...
107
    async def start(self, token: str): ...
108
    async def close(): ...
109
    def run(self, token: str): ...
110

111
class AutoShardedClient(Client):
112
    def __init__(self, *, shard_count: int = None, **options): ...
113
```
114

115
[Client and Connection](./client.md)
116

117
### Guild and Server Management
118

119
Comprehensive server management including member operations, role management, channel organization, moderation tools, and server configuration.
120

121
```python { .api }
122
class Guild:
123
    async def create_text_channel(self, name: str, **options) -> TextChannel: ...
124
    async def create_voice_channel(self, name: str, **options) -> VoiceChannel: ...
125
    async def ban(self, user: nextcord.abc.Snowflake, **options): ...
126
    async def kick(self, user: Member, reason: str = None): ...
127
```
128

129
[Guild Management](./guild.md)
130

131
### Channel System
132

133
Complete channel management for all Discord channel types including text channels, voice channels, stage channels, threads, and forum channels with their specific capabilities.
134

135
```python { .api }
136
class TextChannel(nextcord.abc.Messageable):
137
    async def send(self, content: str = None, **kwargs) -> Message: ...
138
    async def create_thread(self, **kwargs) -> Thread: ...
139

140
class VoiceChannel(nextcord.abc.GuildChannel):
141
    async def connect(**kwargs) -> VoiceClient: ...
142
```
143

144
[Channel System](./channels.md)
145

146
### Message and Communication
147

148
Message handling, content creation, embed formatting, file attachments, and reaction management for rich Discord communication.
149

150
```python { .api }
151
class Message:
152
    async def reply(self, content: str = None, **kwargs) -> Message: ...
153
    async def add_reaction(self, emoji): ...
154
    async def edit(self, **kwargs) -> Message: ...
155

156
class Embed:
157
    def __init__(self, **kwargs): ...
158
    def add_field(self, *, name: str, value: str, inline: bool = True): ...
159
```
160

161
[Messages and Content](./messages.md)
162

163
### Application Commands (Slash Commands)
164

165
Modern Discord application commands including slash commands, user commands, message commands, and their interaction handling.
166

167
```python { .api }
168
def slash_command(*, name: str = None, description: str = None, **kwargs): ...
169
def user_command(*, name: str = None, **kwargs): ...
170
def message_command(*, name: str = None, **kwargs): ...
171

172
class Interaction:
173
    response: InteractionResponse
174
    followup: Followup
175

176
class InteractionResponse:
177
    async def send_message(self, content: str = None, **kwargs): ...
178

179
class Followup:
180
    async def send(self, content: str = None, **kwargs): ...
181
```
182

183
[Application Commands](./application-commands.md)
184

185
### UI Framework
186

187
Interactive Discord UI components including views, buttons, select menus, modals, and text inputs for rich user interactions.
188

189
```python { .api }
190
class View:
191
    def __init__(self, *, timeout: float = 180.0): ...
192
    async def interaction_check(self, interaction: Interaction) -> bool: ...
193

194
class Button(nextcord.ui.Item):
195
    def __init__(self, *, style: ButtonStyle = ButtonStyle.secondary, **kwargs): ...
196

197
class Modal:
198
    def __init__(self, **kwargs): ...
199
    async def on_submit(self, interaction: Interaction): ...
200
```
201

202
[UI Framework](./ui.md)
203

204
### User and Member Management
205

206
User representation, member management, permission handling, and voice state tracking for comprehensive user operations.
207

208
```python { .api }
209
class User:
210
    async def send(self, content: str = None, **kwargs) -> Message: ...
211

212
class Member(User):
213
    async def add_roles(*roles, reason: str = None): ...
214
    async def remove_roles(*roles, reason: str = None): ...
215
    async def timeout(self, until: datetime.datetime, reason: str = None): ...
216
```
217

218
[Users and Members](./users.md)
219

220
### Permission and Role System
221

222
Comprehensive permission management, role operations, and access control for Discord servers.
223

224
```python { .api }
225
class Role:
226
    async def edit(self, **kwargs): ...
227
    async def delete(reason: str = None): ...
228

229
class Permissions:
230
    def __init__(self, permissions: int = 0): ...
231
    def update(self, **kwargs): ...
232
```
233

234
[Permissions and Roles](./permissions.md)
235

236
### Command Framework
237

238
Traditional text-based command system with the commands extension, providing prefix commands, command groups, converters, and checks.
239

240
```python { .api }
241
class Bot(commands.Bot):
242
    def __init__(self, command_prefix, **options): ...
243

244
def command(name: str = None, **kwargs): ...
245
def group(name: str = None, **kwargs): ...
246

247
class Context:
248
    async def send(self, content: str = None, **kwargs) -> Message: ...
249
```
250

251
[Command Framework](./commands.md)
252

253
### Background Tasks
254

255
Task scheduling and background operations with the tasks extension for periodic and scheduled operations.
256

257
```python { .api }
258
def loop(*, seconds: float = None, minutes: float = None, hours: float = None): ...
259

260
class Loop:
261
    def start(self, *args, **kwargs): ...
262
    def stop(self): ...
263
    def restart(self, *args, **kwargs): ...
264
```
265

266
[Tasks and Scheduling](./tasks.md)
267

268
### Webhook System
269

270
Webhook creation and management for external integrations and message delivery outside of bot connections.
271

272
```python { .api }
273
class Webhook:
274
    async def send(self, content: str = None, **kwargs) -> WebhookMessage: ...
275
    async def edit_message(self, message_id: int, **kwargs) -> WebhookMessage: ...
276

277
class SyncWebhook:
278
    def send(self, content: str = None, **kwargs) -> WebhookMessage: ...
279
```
280

281
[Webhooks](./webhooks.md)
282

283
### Voice and Audio
284

285
Voice connection management, audio playback, and voice state handling for Discord voice features.
286

287
```python { .api }
288
class VoiceClient:
289
    def play(self, source: AudioSource, *, after=None): ...
290
    def stop(self): ...
291
    async def disconnect(self, *, force: bool = False): ...
292

293
class AudioSource:
294
    def read(self) -> bytes: ...
295
```
296

297
[Voice and Audio](./voice.md)
298

299
### Events and Raw Events
300

301
Event handling system for Discord gateway events and raw event data for advanced use cases.
302

303
```python { .api }
304
@bot.event
305
async def on_message(message: Message): ...
306

307
@bot.event
308
async def on_raw_message_delete(payload: RawMessageDeleteEvent): ...
309
```
310

311
[Events](./events.md)
312

313
### Utilities and Helpers
314

315
Utility functions, helper classes, and convenience methods for common Discord bot operations.
316

317
```python { .api }
318
def find(predicate, iterable): ...
319
def get(iterable, **attrs): ...
320
def oauth_url(client_id: int, *, permissions: Permissions = None, **kwargs) -> str: ...
321
```
322

323
[Utilities](./utilities.md)
324

325
### Error Handling
326

327
Exception hierarchy and error handling patterns for robust Discord bot development.
328

329
```python { .api }
330
class DiscordException(Exception): ...
331
class HTTPException(DiscordException): ...
332
class Forbidden(HTTPException): ...
333
class NotFound(HTTPException): ...
334
```
335

336
[Error Handling](./errors.md)