Install & Compatibility
Where this runs
tested against v8.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.712s · 24.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.628s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Reddit
✓ from praw import Reddit
✗ import praw
This quickstart demonstrates how to initialize PRAW for both read-only (if only client_id, client_secret, and user_agent are provided) or authenticated (if username and password are also provided) access. It then shows how to fetch popular posts from a subreddit. Credentials should ideally be stored in a `praw.ini` file or environment variables, not hardcoded.
import praw
import os
# It's recommended to use a praw.ini file or environment variables for credentials.
# For quickstart, we'll use environment variables.
reddit = praw.Reddit(
client_id=os.environ.get("REDDIT_CLIENT_ID", ""),
client_secret=os.environ.get("REDDIT_CLIENT_SECRET", ""),
password=os.environ.get("REDDIT_PASSWORD", ""),
user_agent=os.environ.get("REDDIT_USER_AGENT", "my_unique_user_agent_string_v1.0 (by u/YOUR_REDDIT_USERNAME)"),
username=os.environ.get("REDDIT_USERNAME", ""),
)
# Example: Get top 5 hot posts from r/python
print("Top 5 hot posts from r/python:")
for submission in reddit.subreddit("python").hot(limit=5):
print(f"- {submission.title} (Score: {submission.score})")
# Example: Access your inbox (requires authenticated instance)
# try:
# for message in reddit.inbox.unread(limit=5):
# print(f"New message: {message.subject}")
# message.mark_read()
# except prawcore.exceptions.ResponseException as e:
# print(f"Could not access inbox (read_only instance or invalid auth?): {e}")
# To verify if the instance is read-only:
print(f"Is Reddit instance read-only? {reddit.read_only}")
Debug
Known issues
breakingPRAW 7.x introduced significant changes to exception handling. The `APIException` class was renamed to `RedditAPIException` and now acts as a container for multiple `RedditErrorItem` objects, requiring iteration to access individual errors.fixUpdate `except APIException` to `except RedditAPIException as exception:` and iterate through `exception.items` to process individual errors (e.g., `item.error_type`). Direct attribute access like `exception.error_type` on `RedditAPIException` will only work for single errors and is not recommended.
affects: 7.0.0 and later
deprecatedStarting with PRAW 8, most functions and methods will no longer support positional arguments, requiring all arguments to be passed as keyword arguments.fixRefactor your code to explicitly use keyword arguments for all function and method calls (e.g., `reddit.subreddit('test').submit(title='Title', selftext='Body')` instead of `reddit.subreddit('test').submit('Title', 'Body')`). affects: PRAW 7.x (deprecation warning), PRAW 8.0.0 and later (breaking)
deprecatedThe configuration setting `refresh_token` (whether in `praw.ini`, as a keyword argument to `praw.Reddit`, or via `PRAW_REFRESH_TOKEN` environment variable) is deprecated.fixUse the new `token_manager` keyword argument when initializing `praw.Reddit` with an instance of `BaseTokenManager` (e.g., `FileTokenManager` or `SQLiteTokenManager`) to handle refresh tokens.
affects: PRAW 7.2.0 and later
gotchaAttempting to perform write actions (e.g., posting, commenting, upvoting) with a read-only `praw.Reddit` instance will result in errors like `prawcore.exceptions.Redirect: Redirect to /r/subreddit/login/` or `invalid_grant`. This often happens when credentials for an authenticated session (username, password, refresh_token) are missing or incorrect.fixEnsure your `praw.Reddit` instance is properly authenticated with a username and password or a refresh token if you intend to perform actions that modify Reddit. Double-check your `client_id`, `client_secret`, `username`, and `password`. If 2FA is enabled, use a refresh token.
affects: All versions
gotchaAll requests to Reddit's API must include a unique and descriptive User-Agent string. Failure to provide one, or providing a generic one, can lead to your requests being blocked or rate-limited.fixAlways provide a descriptive `user_agent` when initializing `praw.Reddit` in the format `<platform>:<app ID>:<version string> (by u/<Reddit username>)`. For example: `user_agent='android:com.example.myredditapp:v1.2.3 (by u/kemitche)'`.
affects: All versions
Upgrade
Version history
8.0.3latest on PyPI · released Aug 12, 2026
Audit
Dependencies
prawcorerequiredLow-level communication layer for PRAW 4+