🎮 itch-dl

Bulk download games from itch.io with ease

TypeScript implementation for modern Node.js environments

🚀 Quick Start • 📖 Documentation • 💾 Installation • 🎯 Examples • 🐛 Troubleshooting

✨ Features

🎯 What You Can Download

• 🏆 Game Jams - All submissions from any itch.io game jam
• 🔥 Browse Pages - Popular games, newest releases, or games by specific tags
• 📂 Collections - Your personal collections or any public collection
• 📚 Your Library - Everything you own from your purchases
• 👨‍💻 Creator Pages - Complete catalogues from specific developers
• 🎮 Individual Games - Single games or specific titles

🛠️ Powerful Features

• ⚡ Parallel Downloads - Speed up bulk downloads with concurrent processing
• 🎯 Smart Filtering - Filter by platform, file type, or custom patterns
• 📋 Multiple Input Formats - URLs, JSON files, or plain text lists
• 🔄 Resume Support - Skip already downloaded games automatically
• 🌐 Web Mirroring - Optionally download game page assets
• ⚙️ Configuration Profiles - Save settings for different use cases

🚀 Quick Start

1️⃣ Install globally via npm

npm install -g itch-dl

2️⃣ Get your itch.io API key

Visit itch.io API Keys and generate a new key

3️⃣ Start downloading!

# Download a game jam
itch-dl https://itch.io/jam/gmtk-2023 --api-key YOUR_API_KEY

# Download your entire library
itch-dl https://itch.io/my-purchases --api-key YOUR_API_KEY

💡 Tip: Save your API key in a config file to avoid typing it every time!

💾 Installation

Prerequisites

• Node.js 18+ - Download here
• npm (comes with Node.js)
• itch.io account with API key

📦 Install from npm (Recommended)

npm install -g itch-dl

🔧 Install from source

git clone https://github.com/Wal33D/itch-dl.git
cd itch-dl
npm install && npm run build

📚 Need help? Check the Installation Guide for detailed instructions.

🎯 Usage Examples

Basic Downloads

# Individual games (tested working examples)
itch-dl https://baraklava.itch.io/manic-miners --api-key YOUR_KEY
itch-dl https://ncase.itch.io/anxiety --api-key YOUR_KEY
itch-dl https://bunmuen.itch.io/shiftatmidnight --api-key YOUR_KEY

# Game jam with all submissions
itch-dl https://itch.io/jam/gmtk-2023 --api-key YOUR_KEY

# Your entire game library
itch-dl https://itch.io/my-purchases --api-key YOUR_KEY

# Specific creator's games
itch-dl https://ncase.itch.io --api-key YOUR_KEY
itch-dl https://bunmuen.itch.io --api-key YOUR_KEY

# Public collection (real example)
itch-dl https://itch.io/c/215689/public-collection --api-key YOUR_KEY

Filtered Downloads

# Only Windows games
itch-dl https://itch.io/jam/gmtk-2023 --filter-files-platform windows --api-key YOUR_KEY

# Only ZIP files
itch-dl https://itch.io/jam/brackeys-12 --filter-files-glob "*.zip" --api-key YOUR_KEY

# Multiple platforms
itch-dl https://itch.io/my-purchases --filter-files-platform windows mac linux --api-key YOUR_KEY

Advanced Usage

# Fast parallel downloads (3 threads)
itch-dl https://itch.io/jam/gmtk-2023 --parallel 3 --api-key YOUR_KEY

# Just list URLs without downloading
itch-dl https://itch.io/jam/brackeys-12 --urls-only --api-key YOUR_KEY

# Download to specific directory
itch-dl https://itch.io/my-purchases --download-to "/games/itch" --api-key YOUR_KEY

# Mirror web assets (images, etc.)
itch-dl https://some-game.itch.io/game --mirror-web --api-key YOUR_KEY

Using Configuration Files

# Use a specific profile
itch-dl https://itch.io/jam/gmtk-2023 --profile windows-only

# See all options
itch-dl --help

🐛 Troubleshooting

Common Issues

"You did not provide an API key"

• Get your API key from itch.io API Keys
• Pass it with --api-key YOUR_KEY or set ITCH_API_KEY environment variable

"TypeError: data.owned*keys is not iterable" *(Fixed in v0.6.4)_

• This was resolved in version 0.6.4
• Update to the latest version: npm update -g itch-dl

Empty results for my-purchases

• This is normal if you haven't purchased any games on itch.io
• Free games need to be downloaded individually by URL

Collection downloads fail

• Ensure the collection is public
• Private collections require you to be the owner or have access

Network timeouts

• Use --parallel 1 to reduce concurrent requests
• Check your internet connection and try again

Getting Help

If you encounter issues:

1. Check the GitHub Issues
2. Review the wiki documentation
3. Create a new issue with details about your problem

🧪 Help Wanted: Testing

We need community help! We've tested extensively with free games, but need testers who have:

• 💰 Purchased games on itch.io to test paid game downloads
• 📦 Bundle access to test bundle functionality (currently unsupported)
• 🔐 Access-restricted games to verify behavior

See our Testing Request Discussion or check the Tested Games wiki for details!

📚 Documentation

| 📖 Guide | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------ | | Usage Guide | Complete command-line reference with examples | | API Keys | How to get and securely use your itch.io API key | | Configuration | Config files, profiles, and environment variables | | Installation | Detailed installation instructions and troubleshooting | | Tested Games | List of games and URLs verified to work with itch-dl | | Troubleshooting | Common issues and their solutions |

⚠️ Important Notes

✅ What This Tool Does

• Downloads games you legitimately own or have access to
• Respects itch.io's terms of service and rate limits
• Provides the same access as the official itch.io app
• Requires an API key for all operations - even fetching public game information

❌ What This Tool Does NOT Do

• Download paid games for free (you must own them)
• Bypass access restrictions or DRM
• Download from bundles directly (workaround available)

🚧 Current Limitations

• Access-restricted games - Not supported (#16)
• Bundles - Requires workaround (#11)

🔧 Development

Building & Testing

git clone https://github.com/Wal33D/itch-dl.git
cd itch-dl
npm install

# Development commands
npm run build        # Compile TypeScript
npm test            # Run test suite
npm run clean       # Clean build artifacts

Running from Source

npm run build
node build/src/index.js --help

🤝 Contributing

We welcome contributions! Here's how to get started:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch: git checkout -b feature/amazing-feature
3. 💻 Make your changes
4. ✅ Test your changes: npm test
5. 📝 Commit your changes: git commit -m 'Add amazing feature'
6. 🚀 Push to your branch: git push origin feature/amazing-feature
7. 🔄 Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits & Acknowledgments

• Author: Wal33D
• Contributors: See all contributors
• Inspired by: The original Python implementation concept

🔗 Links & Resources

Made with ❤️ for the itch.io community

If this tool helped you, consider ⭐ starring the repository!