How to Export Twitter Followers to CSV with Python (2026)
Build a resumable Python exporter that saves Twitter follower profiles to CSV with cursor checkpoints, deduplication, retries, and formula-prefix hardening.
Export Twitter followers to CSV with a Python script that resumes after interruptions. It resolves a username, follows the available cursors, and writes profiles to CSV as they arrive.
It also prevents duplicate rows during a resumed run and hardens common formula-leading cells. Because CSV files do not define column types, the tutorial also explains how to import long follower IDs without letting a spreadsheet convert them to numbers.
Checked September 23, 2026 with SDK 2.4.0 and simulated API responses.
Disclaimer: TweetAPI is a third-party service. Not affiliated with X Corp.
Download and Run a Small Export
Download export_followers.py (September 23, 2026). This is the same script explained below. Follow the prerequisites, then run it against an existing public account:
python export_followers.py YOUR_USERNAME --output followers.csv --max-pages 2
Replace YOUR_USERNAME; keep the same output and checkpoint files when resuming. Start with two pages to measure returned data and request usage before removing the limit.
The CSV includes profile fields such as these (illustrative values; only three columns shown):
id,username,followerCount
1234567890123456789,example_account,1234
Import IDs as text so spreadsheet software does not round them. The script and its limits are explained below.
What You Will Build
The exporter accepts a Twitter username and produces a CSV with these fields:
- user ID, username, and display name;
- bio, location, and website;
- verification and protected-account flags;
- follower, following, post, and listed counts; and
- account creation time.
The workflow makes one user lookup to resolve the account ID, then one followers request for each cursor page. The script never holds full profile objects for the entire export in memory.
Prerequisites
You need Python, a TweetAPI account, and an API key. Install the maintained Python client:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install tweetapi==2.4.0
The commands above use macOS/Linux. On Windows, create the environment with py -3 -m venv .venv, activate it with .\.venv\Scripts\Activate.ps1, and use python -m pip install tweetapi==2.4.0.
Keep the key outside the script:
export TWEETAPI_KEY="your_api_key"
In PowerShell, use $env:TWEETAPI_KEY = "your_api_key" instead. Keep keys out of source control.
The package currently declares Python 3.9 or newer. For a new production environment, choose a version that is still listed as supported in the Python version status table.
Complete Python Follower Exporter
Save this as export_followers.py:
import argparse
import csv
import json
import os
from pathlib import Path
from typing import Any, Optional
from tweetapi import (
AuthenticationError,
NetworkError,
RateLimitError,
TweetAPI,
TweetAPIError,
)
CSV_FIELDS = [
"id",
"username",
"name",
"bio",
"location",
"website",
"verified",
"isBlueVerified",
"isProtected",
"followerCount",
"followingCount",
"tweetCount",
"listedCount",
"createdAt",
]
DANGEROUS_FORMULA_PREFIXES = (
"=",
"+",
"-",
"@",
"\t",
"\r",
"\n",
"=",
"+",
"-",
"@",
)
def csv_value(value: Any) -> str:
"""Normalize a value and harden common spreadsheet formula prefixes."""
if value is None:
return ""
if isinstance(value, (dict, list)):
value = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
text = str(value).replace("\x00", "")
if text.startswith(DANGEROUS_FORMULA_PREFIXES):
return "'" + text
return text
def read_existing_ids(output_path: Path) -> set[str]:
"""Read only IDs, not full profiles, to deduplicate a resumed export."""
if not output_path.exists() or output_path.stat().st_size == 0:
return set()
with output_path.open("r", encoding="utf-8", newline="") as handle:
return {
row["id"]
for row in csv.DictReader(handle)
if row.get("id")
}
def load_checkpoint(checkpoint_path: Path, username: str) -> dict[str, Any]:
if not checkpoint_path.exists():
return {"username": username, "pages": 0, "rows": 0}
state = json.loads(checkpoint_path.read_text(encoding="utf-8"))
if state.get("username", "").lower() != username.lower():
raise ValueError(
f"Checkpoint belongs to @{state.get('username')}, not @{username}"
)
return state
def save_checkpoint(checkpoint_path: Path, state: dict[str, Any]) -> None:
checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
temporary_path = checkpoint_path.with_name(checkpoint_path.name + ".tmp")
temporary_path.write_text(
json.dumps(state, indent=2, sort_keys=True),
encoding="utf-8",
)
temporary_path.replace(checkpoint_path)
def export_followers(
username: str,
output_path: Path,
checkpoint_path: Path,
max_pages: Optional[int],
) -> None:
client = TweetAPI(api_key=os.environ["TWEETAPI_KEY"])
state = load_checkpoint(checkpoint_path, username)
if state.get("completed"):
print(f"Export is already complete: {output_path}")
return
user_id = state.get("userId")
if not user_id:
profile = client.user.get_by_username(username=username)
user_id = profile["data"]["id"]
state["userId"] = user_id
save_checkpoint(checkpoint_path, state)
output_path.parent.mkdir(parents=True, exist_ok=True)
seen_ids = read_existing_ids(output_path)
state["rows"] = len(seen_ids)
has_header = output_path.exists() and output_path.stat().st_size > 0
pages_this_run = 0
cursor = state.get("cursor")
with output_path.open("a", encoding="utf-8", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=CSV_FIELDS)
if not has_header:
writer.writeheader()
while max_pages is None or pages_this_run < max_pages:
page = client.user.get_followers(user_id=user_id, cursor=cursor)
for follower in page.get("data", []):
follower_id = str(follower.get("id", ""))
if not follower_id or follower_id in seen_ids:
continue
writer.writerow(
{
field: csv_value(follower.get(field))
for field in CSV_FIELDS
}
)
seen_ids.add(follower_id)
state["rows"] = state.get("rows", 0) + 1
handle.flush()
pages_this_run += 1
state["pages"] = state.get("pages", 0) + 1
cursor = page.get("pagination", {}).get("nextCursor")
state["cursor"] = cursor
state["completed"] = not bool(cursor)
save_checkpoint(checkpoint_path, state)
print(
f"pages={state['pages']} rows={state['rows']} "
f"next_cursor={'yes' if cursor else 'no'}"
)
if not cursor:
break
if cursor and max_pages is not None:
print("Stopped at --max-pages. Run the same command to resume.")
else:
print(f"Export complete: {output_path}")
def main() -> None:
parser = argparse.ArgumentParser(
description="Export Twitter follower profiles to a resumable CSV file."
)
parser.add_argument("username", help="Twitter username, with or without @")
parser.add_argument("--output", default="followers.csv")
parser.add_argument(
"--checkpoint",
help="Defaults to <output>.checkpoint.json",
)
parser.add_argument(
"--max-pages",
type=int,
help="Stop after this many pages in the current run",
)
args = parser.parse_args()
username = args.username.lstrip("@").strip()
if not username:
parser.error("username cannot be empty")
if args.max_pages is not None and args.max_pages < 1:
parser.error("--max-pages must be at least 1")
if "TWEETAPI_KEY" not in os.environ:
parser.error("set TWEETAPI_KEY before running the exporter")
output_path = Path(args.output)
checkpoint_path = Path(
args.checkpoint or f"{output_path}.checkpoint.json"
)
try:
export_followers(
username=username,
output_path=output_path,
checkpoint_path=checkpoint_path,
max_pages=args.max_pages,
)
except AuthenticationError:
raise SystemExit("Authentication failed. Check TWEETAPI_KEY.")
except RateLimitError as error:
retry_after = getattr(error, "retry_after", None)
detail = f" Retry after about {retry_after} seconds." if retry_after else ""
raise SystemExit("Rate limit reached." + detail)
except NetworkError:
raise SystemExit("Network request failed after SDK retries.")
except (OSError, ValueError) as error:
raise SystemExit(f"Local export error: {error}")
except TweetAPIError as error:
raise SystemExit(
f"TweetAPI error {error.status_code}: {error.message}"
)
if __name__ == "__main__":
main()
Run a bounded test first:
python export_followers.py nasa --output nasa-followers.csv --max-pages 2
Inspect the CSV and checkpoint. If both look correct, repeat the same command without --max-pages:
python export_followers.py nasa --output nasa-followers.csv
The second command resumes at the saved cursor. It does not start the collection again.
How Resume and Deduplication Work
After every successful page, the script flushes the CSV and atomically replaces the checkpoint file. The checkpoint records the account ID, next cursor, completed page count, and written row count.
On restart, the exporter reads IDs already present in the CSV. If the process stopped after writing a row but before saving the page cursor, requesting that page again will not create duplicate rows.
The restart also reconciles the checkpoint's row count with the IDs already in the CSV. That keeps the reported count accurate across the same write-before-checkpoint interruption window.
Keep the CSV and its .checkpoint.json file together until the export is complete. To intentionally start over, choose new output and checkpoint filenames. Do not attach an old checkpoint to a different CSV.
What Formula-Prefix Hardening Does
A Twitter name, bio, or location can begin with =, +, -, @, a control character, or a full-width equivalent. Some spreadsheet applications can interpret those prefixes as formulas. The exporter adds a leading apostrophe when a cell starts with =, +, -, @, tab, carriage return, line feed, or the corresponding full-width characters.
The Python csv module handles quoting, commas, line breaks, and UTF-8 text. Do not replace csv.DictWriter with string concatenation.
Spreadsheet applications differ in how they handle these prefixes, including after a file is saved and reopened. If the file contains untrusted profile text, follow the OWASP CSV injection guidance for the application and workflow you use.
Import Follower IDs as Text
The CSV stores follower IDs digit for digit, but CSV has no schema that marks the id column as text. Spreadsheet applications can therefore interpret a long Snowflake ID as a number. Excel documents a 15-significant-digit numeric limit, which is shorter than many Twitter IDs.
When ID integrity matters, import the file through the spreadsheet's text/CSV import flow and set the id column to Text before loading it. Do not rely on opening the CSV directly and saving it again. Microsoft's large-number import guidance shows the Text-column workflow for Excel.
Estimate Requests Before a Full Export
The exact request count depends on the number of cursor pages returned, not only the public follower count:
total API requests = 1 username lookup + follower pages requested
For example, a test capped at 10 pages makes at most 11 API calls before SDK retry attempts: one lookup and ten page requests. A resumed run normally reuses the saved account ID, so it does not repeat the username lookup.
Do not calculate cost from an assumed number of followers per page. Page sizes can vary, and the documented contract is the presence of data plus pagination.nextCursor. Use a small --max-pages run to measure the current workload, then compare it with current TweetAPI plans.
Production Improvements for Large Exports
The script stores only seen IDs in memory, but that set still grows with the CSV. For multi-million-row jobs, move deduplication into SQLite or a database table with the user ID as a unique key.
Other useful production changes are:
- upload completed CSV parts to object storage instead of one local disk;
- record job status and cursor in a database;
- split output files after a fixed row count;
- emit metrics for pages, rows, retries, and failures; and
- encrypt or restrict access to files containing profile data.
The SDK already retries transient 429, 5xx, timeout, and connection failures. A production queue should still bound concurrency and total request volume. The complete Python and TypeScript SDK guide explains retry and typed-error behavior.
Data and Completeness Limits
Accounts can gain or lose followers while the export runs, and profile fields can change after a row is written. The rows may therefore reflect different points in time.
The script only exports data returned by the API. Protected, unavailable, suspended, deleted, or otherwise inaccessible accounts may be missing. It cannot reconstruct a complete historical follower list.
Store only the fields your use case needs. Apply appropriate retention, access control, and deletion handling for your users and jurisdiction.
FAQ
Can I export followers without loading everything into memory?
Yes, but the set of seen IDs still grows with the export. See large-export memory limits.
Can I stop and continue later?
Yes. Reuse the same username, CSV, and checkpoint. See how resuming works.
Does the exporter include email addresses?
No. The selected fields come from the public user response and do not include email addresses.
Can I export following instead of followers?
Use the corresponding following endpoint and SDK method, then keep the same checkpoint and CSV pattern. Confirm its current request parameters in the API reference before changing the script.
Run the First Two Pages
Run the two-page command, then inspect the CSV and checkpoint before continuing the export.