Exporting Twitter/X Followers list to Excel

Hey team, Darian here. A few months back, I was working on a side project and found myself manually checking the profiles of new followers to gauge audience interest. It was a tedious process, eating up a couple of hours each week. That’s when I built this little Python utility. Automating the export of follower data into a clean Excel sheet saved me that time and gave me a structured dataset to actually analyze. It’s a simple, high-value script that I think you’ll find useful.

This tutorial will walk you through setting it up. We’re busy people, so I’ll stick to the essentials and get you from zero to a working script as efficiently as possible.

Prerequisites

• X (Twitter) Developer Account: You’ll need access to the v2 API. The free tier is usually sufficient for this task, but check their latest access levels.
• API Credentials: Specifically, you’ll need your Bearer Token. Keep it handy.
• Python 3: A modern version of Python installed on your system.
• Required Python Libraries: You’ll need tweepy, pandas, python-dotenv, and openpyxl. You can install these using pip, for example: pip install tweepy pandas python-dotenv openpyxl.

The Guide: Step-by-Step

Step 1: Securely Store Your Credentials

First things first, we never hardcode secrets directly in our scripts. It’s a security risk and makes the code difficult to manage. In my production setups, I always use environment variables. For local development, a config file is perfect.

Create a file in your project directory named config.env. Note that I’m using this name instead of the more common .env to avoid potential issues with file handling on some systems. Inside this file, add your Bearer Token:

TWITTER_BEARER_TOKEN="YOUR_BEARER_TOKEN_HERE"

Our Python script will read this file securely, keeping your token out of the main codebase.

Step 2: The Python Script

Alright, let’s get to the core logic. I’ll skip the standard virtual environment setup since you likely have your own workflow for that. Let’s jump straight to the Python code. Create a file named export_followers.py.

Here’s the full script. I’ll break down what each part does below.

import tweepy
import pandas as pd
import os
from dotenv import load_dotenv
import time

def get_followers_data():
    # --- Part 1: Load Credentials & Authenticate ---
    load_dotenv('config.env')
    bearer_token = os.getenv('TWITTER_BEARER_TOKEN')

    if not bearer_token:
        print("Error: TWITTER_BEARER_TOKEN not found in config.env")
        return

    try:
        client = tweepy.Client(bearer_token, wait_on_rate_limit=True)
    except Exception as e:
        print(f"Error creating Tweepy client: {e}")
        return

    # --- Part 2: Get Your User ID ---
    # The API needs the ID of the user whose followers you want to fetch.
    # Replace 'YOUR_TWITTER_HANDLE' with the target username.
    target_username = 'YOUR_TWITTER_HANDLE' 
    try:
        user_response = client.get_user(username=target_username)
        if not user_response.data:
            print(f"Could not find user: {target_username}")
            return
        user_id = user_response.data.id
    except Exception as e:
        print(f"Error fetching user ID: {e}")
        return

    print(f"Found user ID for {target_username}: {user_id}")

    # --- Part 3: Paginate Through Followers ---
    followers_data = []
    print("Starting to fetch followers... this may take a while for large accounts.")

    try:
        # tweepy.Paginator handles the complex pagination logic for us.
        # We specify the fields we want to get back for each follower.
        for response in tweepy.Paginator(client.get_users_followers,
                                         id=user_id,
                                         max_results=1000,
                                         user_fields=["public_metrics", "description", "location", "created_at", "verified"]):
            if response.data:
                for user in response.data:
                    followers_data.append({
                        'ID': user.id,
                        'Name': user.name,
                        'Username': user.username,
                        'Followers': user.public_metrics.get('followers_count', 0),
                        'Following': user.public_metrics.get('following_count', 0),
                        'Tweet Count': user.public_metrics.get('tweet_count', 0),
                        'Description': user.description,
                        'Location': user.location,
                        'Created At': user.created_at,
                        'Verified': user.verified
                    })
                print(f"Fetched {len(followers_data)} followers so far...")

    except Exception as e:
        print(f"An error occurred while fetching followers: {e}")

    if not followers_data:
        print("No followers found or an error occurred before data could be fetched.")
        return

    # --- Part 4: Export to Excel ---
    print("Converting data to DataFrame...")
    df = pd.DataFrame(followers_data)

    output_filename = f"{target_username}_followers.xlsx"
    print(f"Saving data to {output_filename}...")
    df.to_excel(output_filename, index=False, engine='openpyxl')
    print("Export complete!")

if __name__ == "__main__":
    get_followers_data()

Code Breakdown:

• Part 1: Authentication: The script starts by using python-dotenv to load our config.env file. It then initializes the Tweepy client with our Bearer Token. I’ve set wait_on_rate_limit=True, which is a lifesaver. It makes Tweepy automatically pause and retry when we hit an API rate limit, preventing the script from crashing.
• Part 2: Get User ID: The followers endpoint requires a user’s numerical ID, not their username (@handle). This block converts the target username into its ID. Remember to change 'YOUR_TWITTER_HANDLE' to the account you’re targeting.
• Part 3: Fetching Followers with a Paginator: This is the heart of the script. The X API returns a maximum of 1000 followers per request. To get more, you have to “paginate” through the results. tweepy.Paginator handles this complexity beautifully. We loop through it, and it makes API calls in the background until all followers are retrieved. I’m also specifying which data fields I care about with user_fields.
• Part 4: Exporting to Excel: Once we have all the follower data in a list, we use the powerful Pandas library to convert it into a DataFrame. A DataFrame is essentially a table. From there, it’s a single command, df.to_excel(), to save it as a clean .xlsx file. I use index=False because I don’t need Pandas adding an extra row-number column to my sheet.

Pro Tip: Automation with Cron

To run this automatically, you can set up a cron job. For instance, to run the script every Monday at 2 AM, your cron entry would look something like this. Notice there’s no absolute path to the executable, which is good practice for portability and avoiding WAF rules.

0 2 * * 1 python3 export_followers.py

Just make sure the cron job runs from the directory containing your script and the config.env file.

Common Pitfalls

Here are a couple of areas where I’ve stumbled in the past, so you can avoid them:

• Forgetting Pagination: The number one mistake is making a single API call and wondering why you only got 1000 followers. This is why using Tweepy’s Paginator is so important; it solves this problem elegantly.
• Invalid API Keys: If you get an authentication error, the first thing to check is your Bearer Token. Make sure it’s copied correctly into your config.env file and that your developer app in the X portal is still active.
• API Access Tiers: The X API has different access levels. If the script fails with a permissions error, double-check that your developer account’s access tier includes the endpoint we’re using (users/:id/followers).

Conclusion

And that’s it. You now have a robust, automated way to pull a full follower list into a usable format. This script is a great starting point. From here, you could expand it to analyze bio keywords, track follower growth over time by comparing multiple exports, or even feed the data into other marketing and analytics tools.

Hope this helps you save some time and gain better insights. Let me know if you have any questions.

– Darian Vance

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions