Install & Compatibility
Where this runs
tested against v4.0.0 · 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.378s · 21.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.364s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
prawcore
✓ import prawcore
TrustedAuthenticator
✓ from prawcore import TrustedAuthenticator
Requestor
✓ from prawcore import Requestor
ReadOnlyAuthorizer
✓ from prawcore import ReadOnlyAuthorizer
session
✓ from prawcore import session
This example demonstrates how to use prawcore to fetch a user's trophies. It assumes you have created a Reddit script application and set `PRAWCORE_CLIENT_ID` and `PRAWCORE_CLIENT_SECRET` environment variables. Replace 'YOUR_VALID_USER_AGENT' with a unique and descriptive user agent string.
import os
import pprint
import prawcore
# Ensure these environment variables are set before running:
# PRAWCORE_CLIENT_ID, PRAWCORE_CLIENT_SECRET
client_id = os.environ.get('PRAWCORE_CLIENT_ID', '')
client_secret = os.environ.get('PRAWCORE_CLIENT_SECRET', '')
user_agent = "YOUR_VALID_USER_AGENT"
if not client_id or not client_secret:
print("Error: PRAWCORE_CLIENT_ID and PRAWCORE_CLIENT_SECRET environment variables must be set.")
exit(1)
authenticator = prawcore.TrustedAuthenticator(
prawcore.Requestor(user_agent),
client_id,
client_secret,
)
authorizer = prawcore.ReadOnlyAuthorizer(authenticator)
authorizer.refresh()
with prawcore.session(authorizer) as session:
try:
response = session.request("GET", "/api/v1/user/bboe/trophies")
pprint.pprint(response)
except prawcore.exceptions.ResponseException as e:
print(f"API Error: {e.response.status_code} - {e.response.text}")
except prawcore.exceptions.RequestException as e:
print(f"Request Error: {e}")
Debug
Known issues
breakingPrawcore explicitly follows semantic versioning where only major versions introduce breaking changes to its public interface. Always pin your major version dependency to avoid unexpected breakages.fixUpdate your `install_requires` (e.g., `prawcore >=X.Y, <(X+1)` or `prawcore~=X.Y`) and consult the changelog before upgrading to a new major version.
affects: <3.0.0, 3.x.x
breakingPrawcore 3.0.0 dropped support for Python 3.8. Earlier versions also dropped support for Python 3.6 and 3.7. Ensure your Python environment meets the `~=3.9` requirement.fixUpgrade your Python interpreter to version 3.9 or higher.
affects: 3.0.0+
breakingIn prawcore 3.0.0, the `RateLimiter` attribute `next_request_timestamp` was removed and replaced with `next_request_timestamp_ns`.fixUpdate code referencing `RateLimiter.next_request_timestamp` to use `RateLimiter.next_request_timestamp_ns` instead.
affects: 3.0.0+
gotchaApplications frequently encounter `prawcore.exceptions.OAuthException: invalid_grant`. This usually indicates an issue with your OAuth credentials (Client ID, Client Secret, Username, Password) or an active 2FA on the Reddit account preventing script access.fixDouble-check your `client_id`, `client_secret`, `username`, and `password`. Ensure 2FA is disabled on the Reddit account if using password flow, or that refresh tokens are handled correctly for other flows. Also, verify your user agent is unique and descriptive.
affects: All
gotchaEncountering `prawcore.exceptions.Forbidden` (HTTP 403) means the authenticated user lacks permission for the requested action or resource, such as accessing private subreddits or replying to locked content.fixVerify the Reddit account associated with your credentials has the necessary permissions. Review the specific API endpoint documentation for required scopes and user roles.
affects: All
gotchaOlder versions of prawcore had issues handling Reddit's rate limits, leading to frequent 429 (Too Many Requests) errors. While newer versions improved this, robust error handling for `prawcore.exceptions.ResponseException` and `prawcore.exceptions.RequestException` is crucial for stable bots.fixEnsure you are on the latest prawcore version. Implement `try-except` blocks for `prawcore.exceptions.ResponseException` (to check `response.status_code`) and `prawcore.exceptions.RequestException`, and incorporate retry logic with exponential backoff for network-related issues or rate limits.
affects: All, especially pre-3.0.0
Errors
Common errors & fixes
ImportError: No module named 'prawcore'
The 'prawcore' library is not installed in the Python environment being used, or there's an issue with the Python environment's path preventing it from being found. Prawcore is a dependency of PRAW, so it's usually installed alongside PRAW.
fixInstall the PRAW library, which includes prawcore, using pip: `pip install praw`. Ensure you are installing it in the correct Python environment where your script will run.
prawcore.exceptions.ResponseException: received 401 HTTP response
This error indicates that the authentication credentials (client ID, client secret, username, password) provided to PRAW are incorrect or invalid, preventing successful authorization with the Reddit API.
fixDouble-check all authentication credentials against your Reddit app settings (on Reddit's developer page) and ensure they are correctly passed to `praw.Reddit()` or specified in your `praw.ini` file.
prawcore.exceptions.OAuthException: invalid_grant error processing request
This typically occurs due to an issue with the OAuth grant, often caused by an incorrect username/password combination, an enabled two-factor authentication (2FA) without a corresponding 2FA token or refresh token, or an invalid `user_agent` string.
fixVerify the accuracy of your Reddit username and password. If 2FA is enabled, provide the 2FA token with your password (e.g., 'password:2FA_TOKEN') or use a refresh token for persistent authentication. Also, ensure your `user_agent` is unique and does not contain words like 'bot' if not explicitly configured to do so on Reddit's side.
prawcore.exceptions.NotFound: received 404 HTTP response
This error means that the specific Reddit resource you are trying to access (e.g., a subreddit, submission, or comment) does not exist, or its identifier/URL is incorrect.
fixVerify the existence and correctness of the Reddit resource you are attempting to retrieve. Double-check for typos in subreddit names, submission IDs, or user names.
Upgrade
Version history
4.0.0latest on PyPI · released Jun 13, 2026
Audit
Dependencies
pythonrequiredRequired Python version as specified by prawcore's metadata.