Skip to main content

​
Guild

Represents a Discord guild. This is referred to as a “server” in the official Discord UI.

​
Attributes

​
id
int
The guild’s ID.
​
name
str
The guild name.
​
owner_id
int
The guild owner’s ID. Use Guild.owner instead.
​
icon
Asset | None
Returns the guild’s icon asset, if available.
​
banner
Asset | None
Returns the guild’s banner asset, if available.
​
description
str | None
The guild’s description.
​
member_count
int
Returns the true member count regardless of it being loaded fully or not.
Due to a Discord limitation, in order for this attribute to remain up-to-date and accurate, it requires Intents.members to be specified.
​
members
list[Member]
A list of members that belong to this guild.
​
roles
list[Role]
Returns a list of the guild’s roles in hierarchy order. The first element of this list will be the lowest role in the hierarchy.
​
emojis
tuple[GuildEmoji, ...]
All emojis that the guild owns.
​
stickers
tuple[GuildSticker, ...]
All stickers that the guild owns.
​
channels
list[GuildChannel]
A list of channels that belong to this guild.
​
threads
list[Thread]
A list of threads that you have permission to view.
​
voice_channels
list[VoiceChannel]
A list of voice channels that belong to this guild. This is sorted by the position and are in UI order from top to bottom.
​
text_channels
list[TextChannel]
A list of text channels that belong to this guild. This is sorted by the position and are in UI order from top to bottom.
​
categories
list[CategoryChannel]
A list of categories that belong to this guild. This is sorted by the position and are in UI order from top to bottom.
​
me
Member
Similar to Client.user except an instance of Member. This is essentially used to get the member version of yourself.
​
owner
Member | None
The member that owns the guild.
​
verification_level
VerificationLevel
The guild’s verification level.
​
explicit_content_filter
ContentFilter
The guild’s explicit content filter.
​
default_notifications
NotificationLevel
The guild’s notification settings.
​
features
list[str]
A list of features that the guild has. The features that a guild can have are subject to arbitrary change by Discord.
​
premium_tier
int
The premium tier for this guild. Corresponds to “Nitro Server” in the official UI. The number goes from 0 to 3 inclusive.
​
premium_subscription_count
int
The number of “boosts” this guild currently has.

​
Methods

Returns a member with the given ID.
​
user_id
int
required
The ID to search for.
Returns: Member | None - The member or None if not found.Example:
member = guild.get_member(123456789)
if member:
    print(f"Found {member.name}")
Returns a channel with the given ID.
This does not search for threads.
​
channel_id
int
required
The ID to search for.
Returns: GuildChannel | None - The returned channel or None if not found.Example:
channel = guild.get_channel(123456789)
if channel:
    await channel.send("Hello!")
Returns a thread with the given ID.
​
thread_id
int
required
The ID to search for.
Returns: Thread | None - The returned thread or None if not found.
Returns a role with the given ID.
​
role_id
int
required
The ID to search for.
Returns: Role | None - The role or None if not found.Example:
role = guild.get_role(123456789)
if role:
    print(f"Role: {role.name}")
Returns the first member found that matches the name provided.The name can have an optional discriminator argument, e.g. “Jake#0001” or “Jake” will both do the lookup. However, the former will give a more precise result.
​
name
str
required
The name of the member to lookup with an optional discriminator.
Returns: Member | None - The member in this guild with the associated name, or None if not found.Example:
member = guild.get_member_named("Jake#0001")
if member:
    print(f"Found {member.display_name}")
Retrieves a Member from the guild with the given ID.
​
user_id
int
required
The ID of the member to fetch.
Returns: Member - The member from the guild.Raises: NotFound if the member is not found.Example:
member = await guild.fetch_member(123456789)
print(member.display_name)
Creates a TextChannel for the guild.
You need the manage_channels permission to create the channel.
​
name
str
required
The channel name.
​
category
CategoryChannel | None
The category to place the newly created channel under.
​
position
int
The position in the channel list.
​
topic
str
The channel’s topic.
​
slowmode_delay
int
Specifies the slowmode rate limit for users in this channel, in seconds.
​
nsfw
bool
Whether to mark the channel as NSFW.
​
reason
str
The reason for creating this channel. Shows up on the audit log.
Returns: TextChannel - The channel that was just created.Example:
channel = await guild.create_text_channel("general", topic="General discussion")
await channel.send("Welcome!")
Creates a VoiceChannel for the guild.
You need the manage_channels permission to create the channel.
​
name
str
required
The channel name.
​
category
CategoryChannel | None
The category to place the newly created channel under.
​
position
int
The position in the channel list.
​
bitrate
int
The channel’s preferred audio bitrate in bits per second.
​
user_limit
int
The channel’s limit for number of members that can be in a voice channel.
​
reason
str
The reason for creating this channel. Shows up on the audit log.
Returns: VoiceChannel - The channel that was just created.
Creates a Role for the guild.
You must have the manage_roles permission to do this.
​
name
str
The role name. Defaults to “new role”.
​
permissions
Permissions
The permissions to assign to the role.
​
colour
Colour | int
The colour for the role. (aliased to color as well)
​
hoist
bool
Whether the role should be shown separately in the member list.
​
mentionable
bool
Whether the role should be mentionable by others.
​
reason
str
The reason for creating this role. Shows up on the audit log.
Returns: Role - The newly created role.Example:
role = await guild.create_role(name="Moderator", colour=discord.Colour.blue())
Fetches a mapping of role IDs to their member counts for this guild.Returns: GuildRoleCounts - A mapping of role IDs to their member counts.Example:
counts = await guild.fetch_roles_member_counts()
member_count = counts[123456789]
Bans a user from the guild.
You must have the ban_members permission to do this.
​
user
Snowflake
required
The user to ban from the guild.
​
reason
str
The reason for banning this user. Shows up on the audit log.
​
delete_message_days
int
The number of days worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 7.
Example:
await guild.ban(user, reason="Spam", delete_message_days=7)
Unbans a user from the guild.
You must have the ban_members permission to do this.
​
user
Snowflake
required
The user to unban.
​
reason
str
The reason for unbanning this user. Shows up on the audit log.
Example:
await guild.unban(user, reason="Appeal accepted")
Kicks a user from the guild.
You must have the kick_members permission to do this.
​
user
Snowflake
required
The user to kick from the guild.
​
reason
str
The reason for kicking this user. Shows up on the audit log.
Example:
await guild.kick(member, reason="Violated rules")

Build docs developers (and LLMs) love

Get started for freeTalk to us