A python wrapper for the Reddit API.
Python Shell
Pull request Compare This branch is 1178 commits behind praw-dev:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This is a Python wrapper for Reddit's API, aiming to be as easy to use as possible. Here's a quick peek, getting the first 10 submissions from the 'hot' section of the 'opensource' subreddit.

import reddit
r = reddit.Reddit(user_agent='my_cool_application')
submissions = r.get_subreddit('opensource').get_hot(limit=5)

this displays

[<Submission: 1 :: OpenFOAM: Open Source Computational Fluid Dynamics>,
 <Submission: 9 :: My new open source project, Bunchify>,
 <Submission: 93 :: Arrested while contributing to OpenStreetMap>,
 <Submission: 27 :: DK: 25,000 hospital staff Copenhagen region to use open source office suite >,
 <Submission: 24 :: Eclipse online>]


You can install via pip

pip install reddit

Or via setup.py

python setup.py install

A Few Short Examples

  1. Logging in:

    r.login(user='username', password='password')
  2. Send a message (requires login):

    r.compose_message('bboe', 'Subject Line', 'You are awesome!')
  3. Mark all unread messages as read (requires login):

    for msg in r.user.get_unread(limit=None):
  4. Get the top submissions for r/python:

    submissions = r.get_subreddit('python').get_top(limit=10)
  5. Get comments from a given submission:

    submission = submissions.next()
  6. Comment on a submission (requires login):

  7. Reply to a comment (requires login):

    comment = submission.comments[0]
  8. Voting (requires login):

    # item can be a comment or submission
  9. Deleting (requires login):

    #item can be a comment or submission
  10. Saving a submission (requires login):

  11. Create a SELF submission (requires login):

    r.submit('reddit_api_test', 'submission title', text='body')
  12. Create a URL submission (requires login):

    r.submit('reddit_api_test', 'Google!', url='http://google.com')
  13. Get user karma:

    user = r.get_redditor('ketralnis')
  14. Get saved links (requires login):

  15. Get content newer than a comment or submission's id:

    r.get_subreddit('python').get_top(limit=None, place_holder=submission.id)
  16. (Un)subscribe to a subreddit (requires login):

  17. (Un)friend a user:

  18. Create a subreddit:

                       full_title='my Incredibly Cool Subreddit',
                       description='It is incredible!')
  19. Get flair mappings for a particular subreddit (requires mod privileges):

    item = r.get_subreddit('python').flair_list().next()
  20. Set / update user flair (requires mod privileges):

    r.get_subreddit('python').set_flair('bboe', 'text flair', 'css-class')
  21. Clear user flair (requires mod privileges):

  22. Bulk set user flair (requires mod privileges):

    flair_mapping = [{'user':'bboe', 'flair_text':'dev'},
                     {'user':'pyapitestuser3', 'flair_css_class':'css2'},
                     {'user':'pyapitestuser2', 'flair_text':'AWESOME',
  23. Add flair templates (requires mod privileges):

    r.get_subreddit('python').add_flair_template(text='editable', css_class='foo',
  24. Clear flair templates (requires mod privileges):


Extra usage info

  • All of the listings (list of stories on subreddit, etc.) are generators, not lists. If you need them to be lists, an easy way is to call list() with your variable as the argument.
  • The default limit for fetching stories is 25. You can change this with the limit param. If you don't want a limit, set limit=None. This will return an infinite generator that will continue fetching stories until reddit hiccups (I wouldn't expect more than ~300 stories).

Example Applications/Scripts

Note: these all use very outdated versions of the API. Don't expect them to work with the latest version. I recommend using them as reference only.

  • A comment tracker, which repeatedly looks at new Reddit comments and can take an action if they meet a specified condition. The example use I gave is replying with an automated message if the body of a comment contains a certain word. (Novelty accounts, anyone?)
  • An account cloner. Given two logins and passwords, it will transfer all of the saved links and subscribed subreddits from the first account to the second.
  • A comment generator: it pulls comments from Reddit, puts them in a Markov chain, and periodically outputs random statuses. The statuses can be viewed here.

I hope that this wrapper allows for many more quick and useful applications to be made!



Why is everything so slow?

Usually that has to do with how fast reddit is responding at the moment. Check the site, see if it's responding quicker when accessing it in your browser. Otherwise, we respect the "no more than one API call per two seconds" rule, so if you're trying to do a bunch of quick requests in succession you're going to be spaced out to one call per second. If you're having a specific issue besides something covered by one of those two things, please let us know (or file a ticket) and we'll check it out.

I want to change the sort/time options for a given listing. How do I do that?

This currently isn't a part of the wrapper, but the _get_sorter method in helpers.py is exactly what you want. The parameters you want to change are sort and time. I'll add this to the wrapper shortly.

I want a new feature!

File an enhacement request via github issues.

Something doesn't work. What gives?

File an issue, I'll look into it.

I want to help develop, but I'm lost.

Send me a github message. I can help you get aquainted with the code base, and maybe we can write a wiki page for others, too.


All of the code contained here is licensed by the GNU GPLv3.