twitter-media-downloader

Twitter/X Media Downloader

Download images and videos from X/Twitter using gallery-dl.

Quick Start

Run the download script with a Twitter/X URL:

uv run scripts/download.py "https://x.com/username" --output ./downloads

Supported URL Types

• Single tweets: https://x.com/user/status/1234567890
• User timelines: https://x.com/username
• User media: https://x.com/username/media
• User likes: https://x.com/username/likes (requires auth)
• Bookmarks: https://x.com/i/bookmarks (requires auth)
• Lists: https://x.com/i/lists/1234567890

Authentication

For protected content (likes, bookmarks, private accounts), provide cookies:

uv run scripts/download.py "URL" --cookies /path/to/cookies.txt

Or use browser cookies directly (recommended):

uv run scripts/download.py "URL" --browser firefox

Note: Using --browser firefox is recommended as it automatically extracts cookies from your browser session.

Common Options

Option	Description
--output DIR	Output directory (default: ./downloads)
--cookies FILE	Path to cookies.txt file
--browser NAME	Extract cookies from browser (firefox, chrome, etc.)
--videos-only	Download only videos
--images-only	Download only images
--limit N	Limit number of items to download
--retweets	Include retweets when downloading user timeline
--replies	Include replies when downloading user timeline
--json	Output structured JSON with downloaded file paths
--debug	Enable verbose debug output for troubleshooting

Examples

Download all media from a user:

uv run scripts/download.py "https://x.com/NASA" --output ./nasa_media

Download a single tweet's media:

uv run scripts/download.py "https://x.com/user/status/1234567890"

Download only videos from a user (limit 50):

uv run scripts/download.py "https://x.com/username" --videos-only --limit 50

Download bookmarks with Firefox cookies:

uv run scripts/download.py "https://x.com/i/bookmarks" --browser firefox

JSON Output Mode

For programmatic use (e.g., integration with other skills), use --json to get structured output:

uv run scripts/download.py "https://x.com/user/status/123" --json --videos-only

Output format:

{
  "files": ["/path/to/downloads/twitter_user_123_1.mp4"],
  "tweet_id": "123",
  "output_dir": "/path/to/downloads",
  "url": "https://x.com/user/status/123",
  "success": true,
  "error": null
}

This is used by the twitter-to-reel skill to automatically download videos before creating reels.

Output Structure

Files are saved with the following naming pattern:

{output_dir}/twitter_{username}_{tweet_id}_{num}.{ext}

Troubleshooting

• Rate limiting: Add delays between requests with --sleep 2
• Login required: Use --cookies or --browser for authentication
• Missing videos: Ensure yt-dlp is installed for video downloads
• Debug mode: Use --debug flag for verbose output to diagnose issues