PYPRESENCE(1)

📦 version 4.6.2, in arch rolling

💅 pypresence(1) — the pypresence manual page, but make it make sense

okay so. this is the manual page for pypresence, section 1 of the manual. it's the whole documentation situation. buckle up bestie, we're going in 🫶

✨ NAME ✨

pypresence — pypresence Documentation. that's it. that's the name. iconic of it honestly 👑

🎀 INSTALLATION 🎀

install pypresence with pip. literally one command, you got this:

if you want the last full release (the stable one, the one that slays), use:

pip install pypresence

or if you're feeling brave and want the in-development release (main character energy, slightly unhinged), use:

pip install https://github.com/qwertyquerty/pypresence/archive/master.zip

🦋 LINKS 🦋

Discord Support Server — https://discord.gg/JF3kg77
Qwerty's Patreon (Some doll hairs would be nice) — https://www.patreon.com/qwertyquerty
pypresence GitHub Repository — https://github.com/qwertyquerty/pypresence

🌸 INFORMATION 🌸

💖 About 💖

Pypresence is a wrapper for Discord RPC. you can use it for Rich Presence for your games, as well as other discord integrations. it's giving "your game but now everyone on your friends list can see what you're doing." periodt ✨

⭐ Quickstart ⭐

This page exists for if you have literally no clue what you're doing, or you just need a quick start. (For rich presence)

no literally. this is the "i opened the docs and my eyes glazed over" section. we got you 🫶

The first thing youll want to do is create a Discord RPC app. Here are the steps:

Navigate to https://discord.com/developers/
Click "Create an Application."
Setup the application how you want, give it the name you want, and give it a good image.
Right under the name of your application, locate your Client ID. You will need this later.
Lastly, save your application.

Next, you need to install pypresence. You will need python 3.9+ installed. Here are the steps:

Open command prompt
Type pip install pypresence and hit enter
It should say something near the end that says something like "Successfully installed pypresence".

Now you will need to create the program to set your rich presence. First we need to import what we need, like so:

from pypresence import Presence # The simple rich presence client in pypresence
import time

Next we need to initialize our Rich Presence client. You'll need that Client ID from earlier:

client_id = "ID HERE"  # Put your Client ID in here
RPC = Presence(client_id)  # Initialize the Presence client

Now we need to connect our Client to Discord, so it can send presence updates:

RPC.connect() # Start the handshake loop

Now we need to actually set our rich presence. We can use the update() function for this. There are many options we can use, but for this we will use these:

RPC.update(
   state="Here it is!",
   details="A working presence, from python!",
   name="Rich Presence Example",
) # Updates our presence

Now we need our program to run forever, so we use a while loop.

while True:  # The presence will stay on as long as the program is running
    time.sleep(15) # Can only update rich presence every 15 seconds

Now when you run your program, it should look something like this! [image: Finished Presence] [image] — yeah. that's the good stuff. look at you go 😭💜

🌈 Using Activity Types and Status Display Types 🌈

You can customize how your presence appears by using ActivityType and StatusDisplayType enums. Here's an example:

from pypresence import Presence
from pypresence.types import ActivityType, StatusDisplayType
import time

client_id = "ID HERE"
RPC = Presence(client_id)
RPC.connect()

# Show as "Listening to" instead of "Playing"
RPC.update(
    activity_type=ActivityType.LISTENING,
    details="My Favorite Song",
    state="By My Favorite Artist"
)

# Or use StatusDisplayType to control what appears in the user's status
RPC.update(
    status_display_type=StatusDisplayType.STATE,
    state="Building something awesome",
    details="Using pypresence"
)

while True:
    time.sleep(15)

Available activity types: PLAYING (default), LISTENING, WATCHING, COMPETING

Available status display types: NAME (default - shows app name), STATE, DETAILS

🧚 Making Your Presence Interactive with URLs 🧚

You can make text and images clickable by using URL parameters. When users click on these elements, Discord will open the specified URL:

from pypresence import Presence
import time

client_id = "ID HERE"
RPC = Presence(client_id)
RPC.connect()

# Make state and details clickable
RPC.update(
    state="Playing an Awesome Game",
    state_url="https://example.com/game",
    details="In the Main Menu",
    details_url="https://example.com/game/menu"
)

# Make images clickable
RPC.update(
    large_image="game_logo",
    large_text="My Game",
    large_url="https://example.com/game",
    small_image="status_online",
    small_text="Online",
    small_url="https://example.com/status"
)

while True:
    time.sleep(15)

Available URL parameters: state_url, details_url, large_url, small_url

💅 Examples 💅

Here is a list of examples using pypresence:

🍓 Basic Rich Presence

import time

from pypresence import Presence

client_id = "717091213148160041"  # Fake ID, put your real one here
RPC = Presence(client_id)  # Initialize the client class
RPC.connect()  # Start the handshake loop

print(
    RPC.update(
        state="Here it is!",
        details="A working presence, from python!",
        name="Rich Presence Example",
    )
)  # Set the presence

while True:  # The presence will stay on as long as the program is running
    time.sleep(15)  # Can only update rich presence every 15 seconds

🔥 Rich Presence to show CPU usage

import time

import psutil

from pypresence import Presence

client_id = "64567352374564"  # Fake ID, put your real one here
RPC = Presence(client_id, pipe=0)  # Initialize the client class
RPC.connect()  # Start the handshake loop

while True:  # The presence will stay on as long as the program is running
    cpu_per = round(psutil.cpu_percent(), 1)  # Get CPU Usage
    mem = psutil.virtual_memory()
    mem_per = round(psutil.virtual_memory().percent, 1)
    print(
        RPC.update(
            details="RAM: " + str(mem_per) + "%", state="CPU: " + str(cpu_per) + "%"
        )
    )  # Set the presence
    time.sleep(15)  # Can only update rich presence every 15 seconds

🌸 Rich Presence to loop through quotes

import random
import time

from pypresence import Presence

client_id = "64567352374564"  # Put your Client ID here, this is a fake ID
RPC = Presence(client_id)  # Initialize the Presence class
RPC.connect()  # Start the handshake loop

quotes = [
    "If you can dream it, you can achieve it.",
    "Either write something worth reading or do something worth writing.",
    "You become what you believe.",
    "Fall seven times and stand up eight.",
    "The best revenge is massive success.",
    "Eighty percent of success is showing up.",
    "Life is what happens to you while you’re busy making other plans.",
    "Strive not to be a success, but rather to be of value.",
    "The best time to plant a tree was 20 years ago. The second best time is now.",
    "Everything you’ve ever wanted is on the other side of fear.",
]  # The quotes to choose from

while True:  # The presence will stay on as long as the program is running
    RPC.update(
        details="Famous Quote:", state=random.choice(quotes)
    )  # Set the presence, picking a random quote
    time.sleep(60)  # Wait a wee bit

Furthermore, the following is a list of repositories which use pypresence

👑 DOCUMENTATION 👑

💜 `Presence()`

class Presence(client_id, pipe=0, loop=None, handler=None)

Creates the Presence client ready for usage. your whole presence journey starts here bestie ✨

Parameters

client_id (str) — OAuth2 App ID (found here: https://discord.com/developers/applications/me)
pipe (int) — Pipe that should be used to connect to the Discord client. Defaults to 0, can be 0-9
loop (asyncio.BaseEventLoop) — Your own event loop (if you have one) that PyPresence should use. One will be created if not supplied. Information at https://docs.python.org/3/library/asyncio-eventloop.html
handler (function) — The exception handler pypresence should send asynchronous errors to. This can be a coroutine or standard function as long as it takes two arguments (exception, future). Exception will be the exception to handle and future will be an instance of asyncio.Future

🦋 `connect()`

Initializes the connection - must be done in order to make any updates to Rich Presence. no connection, no presence. them's the rules 💀

Return type pypresence.Response

🎀 `clear(pid=os.getpid())`

Clears the presence. poof. gone. 🙈

Parameters pid (int) — the process id of your game

Return type pypresence.Response

🌈 `close()`

Closes the connection.

Return type pypresence.Response

⭐ `update(**options)`

Sets the user's presence on Discord. this is the main character function fr fr 👑

Parameters

pid (int) — the process id of your game
activity_type (ActivityType) — the type of activity (PLAYING, LISTENING, WATCHING, or COMPETING). See ActivityType Enum for more details. Defaults to PLAYING if not specified.
status_display_type (StatusDisplayType) — which field to display in the status (NAME, STATE, or DETAILS). See StatusDisplayType Enum for more details. Defaults to NAME if not specified.
state (str) — the user's current status
state_url (str) — URL to make the state text clickable (opens when state is clicked)
details (str) — what the player is currently doing
details_url (str) — URL to make the details text clickable (opens when details is clicked)
name (str) — this one's unhinged in the best way: it directly sets what Discord shows in places like the user list 💅
start (int) — epoch time for when the game started (in milliseconds ⏱️)
end (int) — epoch time for when the game ends (also milliseconds, bestie)
large_image (str) — the name of the uploaded image for the large profile artwork 🖼️
large_text (str) — the tooltip that shows on the large image
large_url (str) — a URL that makes the large image clickable (it opens when someone clicks the large image 🔗)
small_image (str) — name of the uploaded image for the small profile artwork ✨
small_text (str) — tooltip for the small image
small_url (str) — a URL to make the small image clickable (opens when the small image gets clicked)
party_id (str) — id of the player's party, lobby, or group 🎉
party_size (list) — current size of the player's party, lobby, or group, plus the max, in this format: [1,4]
join (str) — unique hashed string for chat invitations and ask to join
spectate (str) — unique hashed string for the spectate button 👀
match (str) — unique hashed string for spectate and join
buttons (list) — list of dicts for buttons on your profile, formatted like [{"label": "My Website", "url": "https://qtqt.cf"}, ...] — you can list up to two buttons 🫶
instance (bool) — marks the match as a game session with a specific beginning and end

Return type: pypresence.Response

🎮 ActivityType Enum

The ActivityType enum is literally the vibe check for what kind of activity is being shown. Import it from pypresence.types, no cap.

Available values:

ActivityType.PLAYING (0) — shows "Playing {game name}" (this is the default 👑)
ActivityType.LISTENING (2) — shows "Listening to {name}" 🎧
ActivityType.WATCHING (3) — shows "Watching {name}" 🍿
ActivityType.COMPETING (5) — shows "Competing in {name}" 🏆

Example usage:

from pypresence import Presence
from pypresence.types import ActivityType

RPC = Presence(client_id)
RPC.connect()
RPC.update(
    activity_type=ActivityType.LISTENING,
    details="My Favorite Song",
    state="By My Favorite Artist"
)

Note: Discord only supports activity types 0, 2, 3, and 5. Types 1 (STREAMING) and 4 (CUSTOM) are not available via Rich Presence. So don't come for them, they're just not invited 😭

🪩 StatusDisplayType Enum

The StatusDisplayType enum controls which field from your presence gets displayed in the user's status. Imported from pypresence.types, same as the last one.

Available values:

StatusDisplayType.NAME (0) — displays the application name (the default ✨)
StatusDisplayType.STATE (1) — displays the state field
StatusDisplayType.DETAILS (2) — displays the details field

Example usage:

from pypresence import Presence
from pypresence.types import StatusDisplayType

RPC = Presence(client_id)
RPC.connect()
RPC.update(
    status_display_type=StatusDisplayType.STATE,
    state="Custom Status Message",
    details="What I'm doing"
)

This lets you control what shows up in the user's Discord status bar while keeping all the info in the full Rich Presence display. Main character energy for your status line 💅

🔗 Clickable URLs

The URL parameters (state_url, details_url, large_url, small_url) make text and images in your Rich Presence clickable. When a user clicks the associated element, Discord opens the URL you specified. It's giving interactive ✨

Available URL parameters:

state_url — makes the state text clickable
details_url — makes the details text clickable
large_url — makes the large image clickable
small_url — makes the small image clickable

Example: clickable state and details:

from pypresence import Presence

RPC = Presence(client_id)
RPC.connect()
RPC.update(
    state="Playing an Awesome Game",
    state_url="https://example.com/game",
    details="In the Main Menu",
    details_url="https://example.com/game/menu"
)

Example: clickable images:

RPC.update(
    large_image="game_logo",
    large_text="My Game",
    large_url="https://example.com/game",
    small_image="status_icon",
    small_text="Online",
    small_url="https://example.com/status"
)

Example: combining URLs with buttons:

RPC.update(
    state="Building Something Cool",
    state_url="https://github.com/username",
    details="pypresence with URL support",
    details_url="https://github.com/qwertyquerty/pypresence",
    large_image="project_logo",
    large_url="https://project-website.com",
    buttons=[
        {"label": "View Project", "url": "https://github.com/username/project"},
        {"label": "Documentation", "url": "https://docs.project.com"}
    ]
)

Notes, bestie, read these:

URLs work independently — you can set a URL even without the corresponding text/image field 👀
URLs must be valid HTTP/HTTPS URLs
Clicking the element opens the URL in the user's default browser 🌐
This feature enhances interactivity beyond the traditional button limit (max 2 buttons) 🔥

👑 `Client()`

class Client(client_id, pipe=0, loop=None, handler=None)

Creates the RPC client, ready for usage. Iconic constructor behaviour, honestly.

Parameters

client_id (str) — OAuth2 App ID (found at https://discord.com/developers/applications/me)
pipe (int) — the pipe that should be used to connect to the Discord client. Defaults to 0, can be 0-9
loop (asyncio.BaseEventLoop) — your own event loop (if you have one) that PyPresence should use. One will be created if you don't supply one. Info at https://docs.python.org/3/library/asyncio-eventloop.html
handler (function) — the exception handler pypresence should send asynchronous errors to. This can be a coroutine or a standard function, as long as it takes two arguments (exception, future). exception will be the exception to handle, and future will be an instance of asyncio.Future

start()

Initializes the connection — you must do this in order to run RPC commands. Non-negotiable 🫡

Return type: pypresence.Response

close()

Closes the connection. Bye bestie 👋

authorize(client_id, scopes, rpc_token=None, username=None)

Used to authenticate a new client with your app. By default this pops up a modal in-app that asks the user to authorize access to your app.

Parameters

client_id (str) — OAuth2 application id
scopes (list) — a list of OAuth scopes as strings
rpc_token (str) — one-time use RPC token
username (str) — username to create a guest account with if the user does not have Discord

Return type: pypresence.Response

All the different scopes can be found here: https://discord.com/developers/docs/topics/oauth2

authenticate(token)

Used to authenticate an existing client with your app.

Parameters

token (int) — OAuth2 access token

Return type: pypresence.Response

get_guilds()

Used to get a list of guilds the client is in.

Return type: pypresence.Response

get_channels()

Used to get a guild's channels the client is in.

Return type: pypresence.Response

channel_id()

Used to get a channel the client is in.

Parameters

channel_id (str) — id of the channel to get

Return type: pypresence.Response

set_user_voice_settings(user_id, **options)

Used to get a channel the client is in. (Yes, that's what it says — we're keeping it exactly as written, don't @ me 😭)

Parameters

user_id (str) — user id
pan_left (float) — left pan of the user
pan_right (float) — right pan of the user
volume (int) — the volume of user (defaults to 100, min 0, max 200) 🔊
mute (bool) — the mute state of the user

Return type: pypresence.Response

select_voice_channel(channel_id)

Used to join and leave voice channels, group dms, or dms.

Parameters

channel_id (str) — channel id to join (or None to leave)

Return type: pypresence.Response

get_selected_voice_channel()

Used to get the client's current voice channel.

Return type: pypresence.Response

select_text_channel(channel_id)

Used to join and leave text channels, group dms, or dms.

Parameters

channel_id (str) — channel id to join (or None to leave)

Return type: pypresence.Response

set_activity(**options)

Used to set the activity shown on Discord profiles and the status of users. Takes the following as parameters.

Parameters

pid (int) — the process id of your game
activity_type (ActivityType) — the type of activity (PLAYING, LISTENING, WATCHING, or COMPETING). See ActivityType Enum <#activity-types> for more details. Defaults to PLAYING if not specified.
status_display_type (StatusDisplayType) — which field to display in the status (NAME, STATE, or DETAILS). See StatusDisplayType Enum <#status-display-types> for more details. Defaults to NAME if not specified.
state (str) — the user's current status
state_url (str) — the URL that makes your state text clickable, so it actually opens something when someone taps it 🖱️
details (str) — what the player is doing right this second
details_url (str) — the URL that makes the details text clickable 😌
name (str) — lets you directly set what Discord shows in places like the user list
start (int) — epoch time for when the game started (in milliseconds!)
end (int) — epoch time for when the game ends (also milliseconds, don't forget 😭)
large_image (str) — name of the uploaded image for the big profile artwork
large_text (str) — tooltip for that large image
large_url (str) — URL to make the large image clickable
small_image (str) — name of the uploaded image for the little corner artwork 🎀
small_text (str) — the "tootltip" for the small image (that spelling is straight from the source, bestie, I don't make the rules 💀)
small_url (str) — URL to make the small image clickable
party_id (str) — id of the player's party, lobby, or group
party_size (list) — current size of the player's party, lobby, or group plus the max, formatted like [1,4]
join (str) — unique hashed string for chat invitations and Ask to Join
spectate (str) — unique hashed string for the spectate button
match (str) — unique hashed string for spectate and join
buttons (list) — list of dicts for the buttons on your profile, formatted like [{"label": "My Website", "url": "https://qtqt.cf"}, ...] — you can list up to two buttons ✨
instance (bool) — marks the match as a game session with a specific beginning and an end

Return type: pypresence.Response

💅 `clear_activity(pid=os.getpid())`

Clears the activity. Poof, gone, the presence is so over.

Parameters:

pid (int) — the process id of your game

Return type: pypresence.Response

🦋 `subscribe(event, args={})`

This is how you subscribe to events, iykyk.

Parameters:

event (str) — the event name you're subscribing to
args (dict) — any args that go along with the event

Return type: pypresence.Response

🌸 `unsubscribe(event, args={})`

The opposite energy: unsubscribe from events.

Parameters:

event (str) — the event name you're unsubscribing from
args (dict) — any args that go along with the event

Return type: pypresence.Response

🎧 `get_voice_settings()`

Grabs the user's voice settings. Nosy but make it useful.

Return type: pypresence.Response

🎚️ `set_voice_settings(**options)`

Sets the user's voice settings. So many knobs, so little time.

Parameters:

_input (dict) — input settings
output (dict) — output settings
mode (dict) — voice mode settings
automatic_gain_control (bool) — state of automatic gain control
echo_cancellation (bool) — state of echo cancellation
noise_suppression (bool) — state of noise suppression
qos (bool) — state of voice quality of service
silence_warning (bool) — state of the silence warning notice
deaf (bool) — state of self-deafen
mute (bool) — state of self-mute

Return type: pypresence.Response

⌨️ `capture_shortcut(action)`

Used to capture a keyboard shortcut that the user enters. Very main character.

Parameters:

action (string) — the capture action, either 'START' or 'STOP'

Return type: pypresence.Response

🫶 `send_activity_join_invite(user_id)`

Used to accept an Ask to Join request. Say yes, bestie.

Parameters:

user_id (str) — user id

Return type: pypresence.Response

🙈 `close_activity_request(user_id)`

Used to reject an Ask to Join request. Gotta respect the no.

Parameters:

user_id (str) — user id

Return type: pypresence.Response

🔥 `register_event(event, func, args={})`

Hooks an event to a function — that function gets called whenever Discord sends that event. It will auto subscribe to the event for you, no cap.

Parameters:

event (str) — the event to hook
func (function) — the function to pair with the event
args (dict) — optional args used in subscription

Return type: pypresence.Response

💜 `unregister_event(event, args={})`

Unhooks an event from a function. It'll auto unsubscribe from that event too, so you don't have to lift a finger.

Parameters:

event (str) — the event to unhook
args (dict) — optional args used in unsubscription

Return type: pypresence.Response

🌈 AUTHOR 🌈

qwertyquerty, LewdNeko — the icons who built this whole thing 👑

🎀 COPYRIGHT 🎀

2025, qwertyquerty

And that's the whole page, bestie — version 4.6, dated Jul 11, 2026, filed under PYPRESENCE(1). Now go make your Discord presence absolutely iconic ✨💅🦋

📦 where this page comes from

arch rolling: python-pypresence 4.6.2-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

PYPRESENCE(1)

💅 pypresence(1) — the pypresence manual page, but make it make sense

✨ NAME ✨

🎀 INSTALLATION 🎀

🦋 LINKS 🦋

🌸 INFORMATION 🌸

💖 About 💖

⭐ Quickstart ⭐

🌈 Using Activity Types and Status Display Types 🌈

🧚 Making Your Presence Interactive with URLs 🧚

💅 Examples 💅

🍓 Basic Rich Presence

🔥 Rich Presence to show CPU usage

🌸 Rich Presence to loop through quotes

👑 DOCUMENTATION 👑

💜 Presence()

🦋 connect()

🎀 clear(pid=os.getpid())

🌈 close()

⭐ update(**options)

🎮 ActivityType Enum

🪩 StatusDisplayType Enum

🔗 Clickable URLs

👑 Client()

💅 clear_activity(pid=os.getpid())

🦋 subscribe(event, args={})

🌸 unsubscribe(event, args={})

🎧 get_voice_settings()

🎚️ set_voice_settings(**options)

⌨️ capture_shortcut(action)

🫶 send_activity_join_invite(user_id)

🙈 close_activity_request(user_id)

🔥 register_event(event, func, args={})

💜 unregister_event(event, args={})

🌈 AUTHOR 🌈

🎀 COPYRIGHT 🎀

💜 `Presence()`

🦋 `connect()`

🎀 `clear(pid=os.getpid())`

🌈 `close()`

⭐ `update(**options)`

👑 `Client()`

💅 `clear_activity(pid=os.getpid())`

🦋 `subscribe(event, args={})`

🌸 `unsubscribe(event, args={})`

🎧 `get_voice_settings()`

🎚️ `set_voice_settings(**options)`

⌨️ `capture_shortcut(action)`

🫶 `send_activity_join_invite(user_id)`

🙈 `close_activity_request(user_id)`

🔥 `register_event(event, func, args={})`

💜 `unregister_event(event, args={})`