Home - Wal33D/itch-dl GitHub Wiki

🎮 itch-dl Wiki

Complete documentation for the TypeScript itch.io bulk downloader

Everything you need to master itch-dl and download games efficiently

🚀 Quick Navigation

🏁 Getting Started

🎯 Quick Actions

⚡ 30-Second Setup

# 1. Install globally (requires v0.6.4+ for best compatibility)
npm install -g itch-dl

# 2. Get your API key from: https://itch.io/user/settings/api-keys

# 3. Start downloading!
itch-dl https://baraklava.itch.io/manic-miners --api-key YOUR_API_KEY

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

🔧 Latest update: v0.6.4 fixed compatibility issues for users with no purchased games

✨ What itch-dl Can Do

🎯 Download Sources

Type Example Description
🏆 Game Jams https://itch.io/jam/gmtk-2023 All submissions from any jam
🔥 Browse Pages https://itch.io/games/popular Popular, newest, or tagged games
📂 Collections https://itch.io/c/123456/cool-games Your collections or public ones
📚 Your Library https://itch.io/my-purchases Everything you own
👨‍💻 Creator Pages https://dani-games.itch.io/ Complete developer catalogues
🎮 Individual Games https://maddy.itch.io/celeste Single games or titles

🛠️ Powerful Features

  • ⚡ Parallel Downloads - Speed up with concurrent processing
  • 🎯 Smart Filtering - Platform, file type, or pattern filtering
  • 📋 Multiple Inputs - URLs, JSON files, or text lists
  • 🔄 Resume Support - Skip already downloaded content
  • 🌐 Web Mirroring - Download game page assets
  • ⚙️ Configuration Profiles - Save settings for different scenarios

🚧 Current Limitations

❌ Not Supported

  • Access-restricted games - Games with download restrictions
  • Bundles - Direct bundle downloads (workaround available)
  • DRM-protected content - Respects all copy protection

💡 Workarounds Available

  • Bundles: Use userscripts to add bundle games to your library first
  • Large downloads: Use --parallel for faster downloads
  • Filtering: Use glob/regex patterns for precise file selection

📚 Documentation Structure

📖 Core Guides

  • Installation - System requirements, npm setup, troubleshooting
  • API Keys - Getting, securing, and using your itch.io API key
  • Usage - Complete command reference with real examples
  • Configuration - Config files, profiles, environment variables
  • Troubleshooting - Common issues and their solutions

🎯 Quick References

⚠️ 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
  • Supports all standard itch.io download types

🔒 Security & Ethics

  • No piracy: Only downloads content you have legitimate access to
  • API key safety: Your credentials stay on your machine
  • Rate limiting: Built-in protections to avoid overloading itch.io
  • Open source: Full transparency in how downloads work

🆚 TypeScript vs Python Implementation

This TypeScript version offers several advantages:

Feature TypeScript (this) Python Original
Performance ⚡ Faster startup, native async 🐌 Slower startup
Dependencies 📦 npm ecosystem 🐍 pip ecosystem
Installation npm install -g Multiple steps
Configuration JSON files Multiple formats
Maintenance 🔄 Active development 📚 Reference implementation

🤝 Getting Help

💬 Community Support

🔧 Self-Help Resources

🎯 Next Steps

Ready to get started? Follow this path:

  1. 📦 Install itch-dl - Get the tool set up
  2. 🔑 Get your API key - Authentication setup
  3. 📖 Learn the basics - Essential commands
  4. ⚙️ Configure for your needs - Optimize your setup
  5. 🚀 Start downloading! - Begin your itch.io archiving

💡 Remember: This tool helps you organize and backup games you already own. It's designed to complement, not replace, the official itch.io experience.

Happy downloading! 🎮

⚠️ **GitHub.com Fallback** ⚠️