Last Updated: Wednesday 14th August 2013

Python is great language for all sorts of things. Very active developer community creates many libraries which extend the language and make it easier to use various services. One of those libraries is tweepy. Tweepy is open-sourced, hosted on GitHub and enables Python to communicate with Twitter platform and use its API. For an introduction on the library Twython - check out this article.

At the time of writing, the current version of tweepy is 1.13. It was released on January 17, and offers various bug fixes and new functionality compared to the previous version. The 2.x version is being developed but it is currently unstable so a huge majority of the users should use the regular version.

Installing tweepy is easy, it can be cloned from the Github repository:

Or using easy install:

Either way provides you with the latest version.

Using tweepy

Tweepy supports accessing Twitter via Basic Authentication and the newer method, OAuth. Twitter has stopped accepting Basic Authentication so OAuth is now the only way to use the Twitter API.

Here is a sample of how to access the Twitter API using tweepy with OAuth:

The result of this code is the following:
Tweepy Hello World Status

The main difference between Basic and OAuth authentication are the consumer and access keys. With Basic Authentication, it was possible to provide a username and password and access the API, but since 2010 when the Twitter started requiring OAuth, the process is a bit more complicated. An app has to be created at

OAuth is a bit more complicated initially than Basic Auth, since it requires more effort, but the benefits it offers are very lucrative:

  • Tweets can be customized to have a string which identifies the app which was used.
  • It doesn’t reveal user password, making it more secure.
  • It's easier to manage the permissions, for example a set of tokens and keys can be generated that only allows reading from the timelines, so in case someone obtains those credentials, he/she won’t be able to write or send direct messages, minimizing the risk.
  • The application doesn't reply on a password, so even if the user changes it, the application will still work.

After logging in to the portal, and going to "Applications", a new application can be created which will provide the needed data for communicating with Twitter API.

Twiter OAuth Dashboard

This is a screen which has all of the data needed to talk to Twitter network. It is important to note that by default, the app has no access to direct messages, so by going to the settings and changing the appropriate option to “Read, write and direct messages”, you can enable your app to have access to every Twitter feature.

Twitter API

Tweepy provides access to the well documented Twitter API. With tweepy, it's possible to get any object and use any method that the official Twitter API offers. For example, a User object has its documentation at and following those guidelines, tweepy can get the appropriate information.

Main Model classes in the Twitter API are Tweets, Users, Entities and Places. Access to each returns a JSON-formatted response and traversing through information is very easy in Python.

Gives us the following output:

All of the API methods are documented here:

Tweepy StreamingAPI

One of the main usage cases of tweepy is monitoring for tweets and doing actions when some event happens. Key component of that is the StreamListener object, which monitors tweets in real time and catches them.

StreamListener has several methods, with on_data() and on_status() being the most useful ones. Here is a sample program which implements this behavior:

So, this program has a StreamListener implemented and the code is set up to use OAuth. The Stream object is created, which uses that listener as output. Stream, being another important object in tweepy also has many methods, in this case filter() is used with parameters passed. "follow" is a list of followers whose tweets are monitored, and "track" is a list of hashtags which will trigger the StreamListener.

In this example, we have used my user ID to follow and the #pythoncentral hashtag as a condition. After running the program and tweeting this status:

Tweepy "Hello World" with hashtag

The program almost instantly catches the tweet, and calls the on_status() method, which produces the following output in the console:

Besides printing the tweet, in the on_status() method there are some additional things which illustrate the number of possibilities that can be done with the tweet data:

This code traverses through entities, picks the "hashtags" one and for each hashtag the tweet contains, it prints its value. This is just a sample; a complete list of tweet entities is located here:


To sum up, tweepy is a great open-source library which provides access to the Twitter API for Python. Although the documentation for tweepy is a bit scarce and doesn't have many examples, the fact that it heavily relies on the Twitter API, which has excellent documentation, makes it probably the best Twitter library for Python, especially when considering the Streaming API support, which is where tweepy excels. Other libraries like python-twitter provide many functions too, but the tweepy has most active community and most commits to the code in the last year.

Additional resources used for tweepy can be obtained here:

About The Author

  • flora

    Hello everybody,

    Can somebody tell me how to use the count parameter in the filter () in tweepy?
    Please reply ASAP.
    Its urgent.
    Thank you !

  • TonyLima

    I’m working on a script to back up some Twitter data. I can get the authentication url and the PIN. But then I get this error:

    Traceback (most recent call last):
    File “”, line 47, in
    File “build/bdist.macosx-10.9-intel/egg/tweepy/”, line 119, in get_access_token
    tweepy.error.TweepError: HTTP Error 401: Unauthorized

    Any ideas and/or suggestions will be greatly appreciated.

    • Jackson Cooper

      Hi Tony. It depends on what mode you want to run in, as a server or client. If you’re wanting to backup your data, you won’t have to get the access token, only set it (with set_access_token). Also, make sure you’ve given the app you created sufficient credentials.

      • TonyLima

        I think your suggestion about the app credentials is the problem. I’m having other difficulties, but will play with this stuff a bit longer before I bother you again. Thanks, Jackson!


        • Jackson Cooper

          No worries Tony, good luck ;-)

  • TonyLima

    OK, I decided to run the script on my Mac just to see if this was a problem being caused by Windows. Now I’m even more confused. Here’s the error message:

    Traceback (most recent call last):
    File “”, line 66, in
    File “build/bdist.macosx-10.9-intel/egg/tweepy/”, line 200, in _call
    File “build/bdist.macosx-10.9-intel/egg/tweepy/”, line 176, in execute
    tweepy.error.TweepError: [{u’message': u’Sorry, that page does not exist’, u’code': 34}]

    All ideas, suggestions, comments, and criticism gladly accepted. Thanks in advance,

  • bhubaneswari

    getting this error while installing.. plz suggest solution

    C:Python27Libtweepy2>python install
    Traceback (most recent call last):
    File “”, line 4, in
    from tweepy import __version__
    File “”, line 14, in
    from tweepy.api import API
    File “”, line 8, in
    from tweepy.binder import bind_api
    File “”, line 5, in
    import requests
    ImportError: No module named requests

    • Jackson Cooper

      You need to install the requests library. Try pip install requests

  • Jorge Saldivar Galli

    I think there is a little mistake in the code. The parameter “follow” in the method “filter” of “streaming” should receive an array of strings, not an array of integers. So, instead of

    stream.filter(follow=[38744894], track=[‘#pythoncentral’])

    it should be

    stream.filter(follow=[‘38744894′], track=[‘#pythoncentral’])

  • Eman Naguib

    python install …. this error appear why ?
    `Traceback (most recent call last):
    File “”, line 5, in
    from pip.req import parse_requirements
    File “/usr/lib/python2.7/dist-packages/pip/”, line 11, in
    from pip.vcs import git, mercurial, subversion, bazaar # noqa
    File “/usr/lib/python2.7/dist-packages/pip/vcs/”, line 9, in
    from import path_to_url
    File “/usr/lib/python2.7/dist-packages/pip/”, line 25, in
    from requests.compat import IncompleteRead
    ImportError: cannot import name IncompleteRead`

    and in terminal write python , import tweepy
    `Traceback (most recent call last):
    File “”, line 1, in
    File “tweepy/”, line 16, in
    from tweepy.auth import OAuthHandler, AppAuthHandler
    File “tweepy/”, line 9, in
    from requests_oauthlib import OAuth1Session, OAuth1
    File “/usr/local/lib/python2.7/dist-package/requests_oauthlib-0.4.1-py2.7.egg/requests_oauthlib/”, line 3, in
    from .oauth2_auth import OAuth2
    File “/usr/local/lib/python2.7/dist-packages/requests_oauthlib-0.4.1-py2.7.egg/requests_oauthlib/”, line 3, in
    from oauthlib.oauth2 import is_secure_transport
    ImportError: cannot import name is_secure_transport `

    • Jackson Cooper

      Check if $PYTHONPATH is set correctly, and oauthlib’s correctly installed. If not `sudo pip install oauthlib --upgrade`