PYPRESENCE(1)

NAME
pypresence - pypresence Documentation

INSTALLATION

Install pypresence with pip:

For the last full release, you can use:

pip install pypresence

Or for the in-development release, you can 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.

  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)

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]

    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.

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.

Return type
    pypresence.Response

clear(pid=os.getpid())
    Clears the presence.

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.

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) -- directly set what discord will display in places like the user list

•   start (int) -- epoch time for game start (in milliseconds)

•   end (int) -- epoch time for game end (in milliseconds)

•   large_image (str) -- name of the uploaded image for the large profile artwork

•   large_text (str) -- tooltip for the large image

•   large_url (str) -- URL to make the large image clickable (opens when large image is clicked)

•   small_image (str) -- name of the uploaded image for the small profile artwork

•   small_text (str) -- tootltip for the small image

•   small_url (str) -- URL to make the small image clickable (opens when small image is 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, and 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 spectate button

•   match (str) -- unique hashed string for spectate and join

•   buttons (list) -- list of dicts for buttons on your profile in the format [{"label": "My Website", "url": "https://qtqt.cf"}, ...], 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 specifies what type of activity is being displayed. It is imported from pypresence.types.

Available values:

•   ActivityType.PLAYING (0) - Shows "Playing {game name}" (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.

  StatusDisplayType Enum

The StatusDisplayType enum controls which field from your presence is displayed in the user's status. It is imported from pypresence.types.

Available values:

•   StatusDisplayType.NAME (0) - Displays the application name (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 allows you to control what appears in the user's Discord status bar while maintaining all information in the full Rich Presence display.

  Clickable URLs

The URL parameters (state_url, details_url, large_url, small_url) allow you to make text and images in your Rich Presence clickable. When a user clicks on the associated element, Discord will open the specified URL.

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:

•   URLs work independently - you can set a URL even without the corresponding text/image field

•   URLs must be valid HTTP/HTTPS URLs

•   Clicking on the element will open 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.

Parameters

•   client_id (str) -- OAuth2 App ID (found at <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

start()
    Initializes the connection - must be done in order to run RPC commands.

Return type
    pypresence.Response

close()
    Closes the connection.

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.

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 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) -- 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) -- directly set what discord will display in places like the user list

•   start (int) -- epoch time for game start (in milliseconds)

•   end (int) -- epoch time for game end (in milliseconds)

•   large_image (str) -- name of the uploaded image for the large profile artwork

•   large_text (str) -- tooltip for the large image

•   large_url (str) -- URL to make the large image clickable (opens when large image is clicked)

•   small_image (str) -- name of the uploaded image for the small profile artwork

•   small_text (str) -- tootltip for the small image

•   small_url (str) -- URL to make the small image clickable (opens when small image is 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, and 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 spectate button

•   match (str) -- unique hashed string for spectate and join

•   buttons (list) -- list of dicts for buttons on your profile in the format [{"label": "My Website", "url": "https://qtqt.cf"}, ...], 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

clear_activity(pid=os.getpid())
    Clear the activity.

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

Return type
    pypresence.Response

subscribe(event, args={})
    Used to subscribe to events.

Parameters

•   event (str) -- event name to subscribe to

•   args (dict) -- any args to go along with the event

Return type
    pypresence.Response

unsubscribe(event, args={})
    Used to unsubscribe from events.

Parameters

•   event (str) -- event name to unsubscribe from

•   args (dict) -- any args to go along with the event

Return type
    pypresence.Response

get_voice_settings()
    Get the user's voice settings.

Return type
    pypresence.Response

set_voice_settings(**options)
    Set the user's voice settings.

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 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 entered by the user.

Parameters
    action (string) -- capture action, either 'START' or 'STOP'

Return type
    pypresence.Response

send_activity_join_invite(user_id)
    Used to accept an Ask to Join request.

Parameters
    user_id (str) -- user id

Return type
    pypresence.Response

close_activity_request(user_id)
    Used to reject an Ask to Join request.

Parameters
    user_id (str) -- user id

Return type
    pypresence.Response

register_event(event, func, args={})
    Hook an event to a function. The function will be called whenever Discord sends that event. Will auto subscribe to it.

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={})
    Unhook an event from a function. Will auto unsubscribe from the event as well.

Parameters

•   event (str) -- the event to unhook

•   args (dict) -- optional args used in unsubscription

Return type
    pypresence.Response

Author
qwertyquerty, LewdNeko

Copyright
2025, qwertyquerty