Tweepy — Python Client for the Twitter/X API

Introduction

Tweepy is a Python library that simplifies interaction with the Twitter (now X) API. It wraps both the v1.1 REST API and the newer v2 API, handling OAuth authentication, pagination, rate limiting, and streaming so developers can focus on building applications rather than managing HTTP requests.

What Tweepy Does

• Provides a high-level Client class for Twitter API v2 endpoints (tweets, users, spaces, lists)
• Supports the legacy API v1.1 via the API class for media uploads and direct messages
• Handles OAuth 1.0a and OAuth 2.0 (Bearer Token, PKCE) authentication flows
• Offers real-time filtered and sampled stream classes for processing tweets as they arrive
• Manages automatic pagination through cursors and paginators

Architecture Overview

Tweepy is organized around two main client classes: Client for API v2 and API for v1.1. Authentication is handled by separate handler classes (OAuthHandler, OAuth2BearerHandler) that manage token exchange and request signing. The streaming module uses long-lived HTTP connections to receive tweets in real-time, dispatching events to user-defined callbacks. Pagination is abstracted via Paginator, which yields pages or items lazily.

Self-Hosting & Configuration

• Requires Python 3.7 or newer
• Install with pip install tweepy
• Create a Twitter Developer account and generate API keys and tokens
• Set the appropriate access level (Essential, Elevated, Academic) for your use case
• Store credentials in environment variables or a secrets manager, never in code

Key Features

• Dual API support: v2 Client for modern endpoints, v1.1 API for legacy features
• Built-in rate limit handling with configurable wait behavior
• StreamingClient for real-time tweet filtering by keywords, users, or rules
• Automatic response model parsing into Python objects
• Async support via tweepy.asynchronous for non-blocking operations

Comparison with Similar Tools

• python-twitter — Older alternative that only supports API v1.1; Tweepy covers both v1.1 and v2
• twarc — Focused on Twitter data archiving and research; Tweepy is more general-purpose
• snscrape — Scrapes Twitter without API keys but breaks when the site changes; Tweepy uses the official API
• TwitterAPI — Thin wrapper with less abstraction; Tweepy provides more convenience methods and models

FAQ

Q: Does Tweepy work with the X (Twitter) API v2? A: Yes. The tweepy.Client class is specifically designed for API v2 endpoints.

Q: How does Tweepy handle rate limits? A: By default, Tweepy waits automatically when a rate limit is hit. You can disable this with wait_on_rate_limit=False.

Q: Can I stream tweets in real time? A: Yes. Use StreamingClient with filtered stream rules to receive matching tweets as they are posted.

Q: What license does Tweepy use? A: MIT License.

Sources

• https://github.com/tweepy/tweepy
• https://docs.tweepy.org