# Twitter Media Downloader

> Download images and videos from X/Twitter using gallery-dl. Use when user wants to download media from Twitter/X URLs including tweets, user profiles, timelines, or likes. Supports single tweets, entire user media galleries, bookmarks, and lists. Handles authentication via cookies for accessing protected content. Use when this capability is needed.

- Skill: `tomevault-io/twitter-media-downloader` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/twitter-media-downloader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/twitter-media-downloader/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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:

```bash
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:

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

Or use browser cookies directly (recommended):

```bash
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:
```bash
uv run scripts/download.py "https://x.com/NASA" --output ./nasa_media
```

Download a single tweet's media:
```bash
uv run scripts/download.py "https://x.com/user/status/1234567890"
```

Download only videos from a user (limit 50):
```bash
uv run scripts/download.py "https://x.com/username" --videos-only --limit 50
```

Download bookmarks with Firefox cookies:
```bash
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:

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

Output format:
```json
{
  "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:
```text
{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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/bossjones) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-16 -->