praw.ini Files#

PRAW comes with a praw.ini file in the package directory, and looks for user defined praw.ini files in a few other locations:

  1. In the current working directory at the time Reddit is initialized.

  2. In the launching user’s config directory. This directory, if available, is detected in order as one of the following:

    1. In the directory specified by the XDG_CONFIG_HOME environment variable on operating systems that define such an environment variable (some modern Linux distributions).

    2. In the directory specified by $HOME/.config if the HOME environment variable is defined (Linux and Mac OS systems).

    3. In the directory specified by the APPDATA environment variable (Windows).

      Note

      To check the values of the environment variables, you can open up a terminal (Terminal/Terminal.app/Command Prompt/Powershell) and echo the variables (replacing <variable> with the name of the variable):

      MacOS/Linux:

      echo "$<variable>"
      

      Windows Command Prompt

      echo "%<variable>%"
      

      Powershell

      Write-Output "$env:<variable>"
      

      You can also view environment variables in Python:

      import os
      
      print(os.environ.get("<variable>", ""))
      

Format of praw.ini#

praw.ini uses the INI file format, which can contain multiple groups of settings separated into sections. PRAW refers to each section as a site. The default site, DEFAULT, is provided in the package’s praw.ini file. This site defines the default settings for interaction with Reddit. The contents of the package’s praw.ini file are:

[DEFAULT]
# A boolean to indicate whether or not to check for package updates.
check_for_updates=True

# Object to kind mappings
comment_kind=t1
message_kind=t4
redditor_kind=t2
submission_kind=t3
subreddit_kind=t5
trophy_kind=t6

# The URL prefix for OAuth-related requests.
oauth_url=https://oauth.reddit.com

# The amount of seconds of ratelimit to sleep for upon encountering a specific type of 429 error.
ratelimit_seconds=5

# The URL prefix for regular requests.
reddit_url=https://www.reddit.com

# The URL prefix for short URLs.
short_url=https://redd.it

# The timeout for requests to Reddit in number of seconds
timeout=16

Warning

Avoid modifying the package’s praw.ini file. Prefer instead to override its values in your own praw.ini file. You can even override settings of the DEFAULT site in user defined praw.ini files.

Defining Additional Sites#

In addition to the DEFAULT site, additional sites can be configured in user defined praw.ini files. All sites inherit settings from the DEFAULT site and can override whichever settings desired.

Defining additional sites is a convenient way to store OAuth credentials for various accounts, or distinct OAuth applications. For example if you have three separate bots, you might create a site for each:

[bot1]
client_id=revokedpDQy3xZ
client_secret=revokedoqsMk5nHCJTHLrwgvHpr
password=invalidht4wd50gk
username=fakebot1

[bot2]
client_id=revokedcIqbclb
client_secret=revokedCClyu4FjVO77MYlTynfj
password=invalidzpiq8s59j
username=fakebot2

[bot3]
client_id=revokedSbt0zor
client_secret=revokedNh8kwg8e5t4m6KvSrbTI
password=invalidlfo00esyy
username=fakebot3

Choosing a Site#

Site selection is done via the site_name parameter to Reddit. For example, to use the settings defined for bot2 as shown above, initialize Reddit like so:

reddit = praw.Reddit("bot2", user_agent="bot2 user agent")

Note

In the above example you can obviate passing user_agent if you add the setting user_agent=... in the [bot2] site definition.

A site can also be selected via a praw_site environment variable. This approach has precedence over the site_name parameter described above.

Using Interpolation#

By default PRAW doesn’t apply any interpolation on the config file but this can be changed with the config_interpolation parameter which can be set to “basic” or “extended”.

This can be useful to separate the components of the user_agent into individual variables, for example:

[bot1]
bot_name=MyBot
bot_version=1.2.3
bot_author=MyUser
user_agent=script:%(bot_name)s:v%(bot_version)s (by u/%(bot_author)s)

This uses basic interpolation thus Reddit need to be initialized as follows:

reddit = praw.Reddit("bot1", config_interpolation="basic")

Then the value of reddit.config.user_agent will be "script:MyBot:v1.2.3 (by u/MyUser)".

See Interpolation of values for details.

Warning

The configparser.ConfigParser instance is cached internally at the class level, it is shared across all instances of Reddit and once set it’s not overridden by future invocations.