tweepy

Tweepy is the long-running Python client for the X (formerly Twitter) API, giving developers a single package that covers both the legacy v1.1 REST API (through the API class) and the newer v2 API (through the synchronous Client and asyncio-based AsyncClient). Rather than hand-rolling HTTP requests and OAuth signing against Twitter’s API, developers import Tweepy, authenticate with one of its handler classes, and call typed methods that return parsed model objects.

The library has tracked Twitter’s/X’s API evolution since 2009, which means it carries both the original tweet/timeline/direct-message surface and the newer v2 concepts (Tweets, Spaces, Polls, Lists, Media) as first-class model classes. It also ships a Stream/StreamingClient implementation for consuming the filtered and sampled real-time tweet streams, and a Cursor helper that abstracts pagination for both API versions so callers don’t have to manage next_token/cursor bookkeeping by hand.

Because it sits directly on requests (and aiohttp for the async client), Tweepy stays a thin, dependency-light wrapper rather than a heavyweight framework, which is part of why it has remained the default choice for Python scripts, bots, and data-collection tools that talk to the X API.

What You Get

• A Client class for the modern X API v2 (tweets, users, spaces, lists, polls, direct messages) with a typed Response namedtuple of (data, includes, errors, meta)
• An AsyncClient mirroring the same v2 surface built on aiohttp for asyncio-based applications
• The legacy API class for the v1.1 endpoints (status updates, timelines, media upload, direct messages) still used by many long-running integrations
• OAuth1UserHandler and OAuth2 handler classes covering 3-legged OAuth, PIN-based auth, and bearer-token app-only auth
• A Cursor helper that iterates paginated v1.1 endpoints without manual cursor/next_token management
• Stream and StreamingClient classes for consuming X’s filtered and sampled real-time tweet streams

Common Use Cases

• Building a Twitter/X bot that posts, replies, and reacts to mentions on a schedule
• Collecting tweets matching search terms or streaming rules for research or analytics pipelines
• Backend services that need to look up users, tweets, or timelines as part of a larger product
• Data-collection scripts that page through followers, likes, or mentions using the built-in Cursor/pagination helpers
• Academic or journalistic research pulling structured tweet/user data at scale via the v2 Client

Under The Hood

Architecture Tweepy splits cleanly by API generation and transport mode: tweepy/api.py’s API class implements the legacy v1.1 surface as one large class with per-endpoint methods, while tweepy/client.py’s BaseClient/Client pair implements the v2 surface, and tweepy/asynchronous/client.py’s AsyncBaseClient/AsyncClient mirrors the same v2 method set on aiohttp instead of requests. Authentication is factored out into tweepy/auth.py’s OAuth1UserHandler/OAuth2 classes, which either a v1.1 API instance or a v2 Client can take at construction time, decoupling the credential/signing concern from request-shaping. Response modeling is shared through tweepy/mixins.py’s equality/hashing/mapping mixins and tweepy/models.py’s ModelFactory, giving classes like Tweet, User, Space, and List consistent behavior instead of each reimplementing it. Pagination is handled two different ways depending on API generation — tweepy/cursor.py’s Cursor wraps v1.1 endpoints, while v2 methods thread pagination_token/next_token through their own arguments — a v1-vs-v2 seam that runs through auth, pagination, and response parsing rather than being isolated to one module; unifying the two interfaces would touch most of api.py, client.py, and cursor.py.

Tech Stack Tweepy is built directly on requests for synchronous HTTP (both the v1.1 API and v2 Client) and aiohttp for the optional async extra’s AsyncClient, with requests-oauthlib/oauthlib supplying OAuth1 signing and async-lru providing caching for the async client. The base install stays lightweight — oauthlib, requests, and requests-oauthlib are the only hard runtime dependencies, with async, dev, and test as opt-in extras. The package is built with flit_core rather than setuptools and supports Python 3.9 through 3.13 per its CI matrix. Documentation is built with Sphinx and hosted on Read the Docs, and CI runs the unittest suite across all five supported Python versions with Coveralls coverage reporting.

Code Quality Tests live under tests/ as unittest.TestCase subclasses and use vcrpy cassettes (checked into cassettes/) to replay recorded API responses rather than hitting the live X API in CI, keeping tests deterministic; several auth tests explicitly skip themselves when live credentials aren’t configured. Error handling is centralized in tweepy/errors.py’s TweepyException hierarchy (HTTPException, BadRequest, Unauthorized, Forbidden, NotFound, TooManyRequests, TwitterServerError), which parses the API’s own error codes and messages out of the response JSON rather than surfacing a generic HTTP error. The codebase does not use type hints or a static type checker, and no linter/formatter is configured in CI — style consistency relies on convention rather than enforced tooling.

API Design The library’s method-per-endpoint design (Client.create_tweet, Client.get_users_mentions, API.update_status) maps closely to the X API’s own endpoint names, so developers already familiar with the API’s REST documentation can predict Tweepy’s method names without a separate mapping. Getting started requires only a handler instance and one client construction call rather than manual request-signing boilerplate, and the wait_on_rate_limit flag removes the need for callers to hand-write their own backoff logic for the common rate-limit case. The main ergonomic cost is the coexistence of two parallel method sets and response shapes — v1.1’s model objects versus v2’s Response namedtuple of data/includes/errors/meta — which callers must learn to distinguish depending on which API generation an integration targets.