# IMDb Watchlist to Sonarr Sync
Automatically sync TV shows from your IMDb watchlist to Sonarr. This script fetches all TV shows from your IMDb watchlist and adds them to Sonarr with your preferred quality profile and monitoring settings.
[](https://www.python.org/downloads/)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
[](https://github.com/PyCQA/bandit)
## Features
- ✅ **Full Pagination Support** - Processes entire IMDb watchlist (6000+ items)
- ✅ **Secure Configuration** - API keys stored in .env file (never committed)
- ✅ **Smart Filtering** - Only processes TV shows (series, mini-series, TV movies)
- ✅ **Duplicate Detection** - Skips shows already in Sonarr
- ✅ **Direct IMDb Lookups** - No external APIs needed (except Sonarr)
- ✅ **Dry-Run Mode** - Test safely without making changes
- ✅ **Professional Logging** - Timestamped, configurable log levels
- ✅ **Connection Pooling** - Efficient HTTP requests with session reuse
- ✅ **Exponential Backoff** - Automatic retry with smart backoff strategy
- ✅ **Type Safe** - Full type hints and mypy compliance
- ✅ **Production Ready** - Comprehensive error handling and validation
## Quick Start
### 1. Install Dependencies
```bash
# Clone the repository
git clone <repository-url>
cd imdb_watchlist_to_sonarr
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
```
### 2. Configure Your Settings
```bash
# Copy the example configuration
cp .env.example .env
# Edit with your actual values
nano .env # or vim, code, etc.
```
Required settings in `.env`:
```bash
SONARR_URL=http://localhost:8989
SONARR_API_KEY=your_sonarr_api_key_here
IMDB_WATCHLIST_URL=https://www.imdb.com/user/urXXXXXXX/watchlist/
```
### 3. Run the Script
```bash
# Test without making changes (recommended first run)
python3 imdb_watchlist_to_sonarr.py --dry-run
# Or use make for convenience
make dry-run
# When ready, run for real
make run
```
## Usage
### Basic Commands
```bash
# Dry run (safe, no changes made)
make dry-run
# Live run (adds shows to Sonarr)
make run
# Show version
make version
# Show all available commands
make help
```
### Advanced Options
```bash
# Process only first 3 pages (for testing)
python3 imdb_watchlist_to_sonarr.py --dry-run --max-pages 3
# Verbose logging
python3 imdb_watchlist_to_sonarr.py --dry-run --verbose
# Override quality profile
python3 imdb_watchlist_to_sonarr.py --quality-profile "Ultra-HD" --dry-run
# All options
python3 imdb_watchlist_to_sonarr.py --help
```
## Configuration
### .env File (Recommended)
All settings can be configured in `.env`:
```bash
# Sonarr Configuration
SONARR_URL=http://localhost:8989
SONARR_API_KEY=your_api_key
SONARR_ROOT_FOLDER=/Volumes/public/Television
SONARR_QUALITY_PROFILE=HD-1080p
SONARR_MONITOR=all
# IMDb Configuration
IMDB_WATCHLIST_URL=https://www.imdb.com/user/urXXXXXXX/watchlist/
# Script Behavior
DRY_RUN=false
```
See [CONFIGURATION.md](CONFIGURATION.md) for complete documentation.
### Getting Your Configuration Values
**Sonarr API Key:**
1. Open Sonarr → Settings → General → Security
2. Copy the API Key
**IMDb Watchlist URL:**
1. Go to IMDb → Your Watchlist
2. Copy the URL from your browser
3. Format: `https://www.imdb.com/user/urXXXXXXX/watchlist/`
## Development
### Setup Development Environment
```bash
# Install development dependencies
make install-dev
# Run all quality checks
make check-all
# Format code
make format
# Run tests
make test
```
### Code Quality
This project maintains high code quality standards:
- **Linting**: ruff (0 errors)
- **Formatting**: black (100-char lines)
- **Type Checking**: mypy (strict mode)
- **Security**: bandit scanning
- **Testing**: pytest with coverage
Run all checks:
```bash
make check-all
```
## Architecture
### Data Flow
1. **Fetch IMDb Watchlist** → Parse JSON from __NEXT_DATA__ block
2. **Filter TV Shows** → Extract tvSeries, tvMiniSeries, tvMovie
3. **Paginate** → Process all pages (250 items each)
4. **Check Sonarr** → Skip shows already in library
5. **Lookup in Sonarr** → Direct IMDb ID lookup (no TVMaze needed)
6. **Add to Sonarr** → With quality profile and monitoring settings
### Performance
- **Connection Pooling**: Reuses HTTP connections for efficiency
- **Exponential Backoff**: Smart retry strategy (1s → 10s)
- **Batch Processing**: Processes 50 shows at a time with progress indicators
- **Optimized Lookups**: Direct Sonarr IMDb lookups (~40% faster than TVMaze)
## Documentation
- **[QUICKSTART.md](QUICKSTART.md)** - Get started in 2 minutes
- **[CONFIGURATION.md](CONFIGURATION.md)** - Complete configuration guide
- **[IMPROVEMENTS.md](IMPROVEMENTS.md)** - All code quality enhancements
- **[CLAUDE.md](CLAUDE.md)** - Documentation for Claude Code
## Security
This project follows security best practices:
- ✅ API keys stored in `.env` file (not in code)
- ✅ `.env` in `.gitignore` (never committed to git)
- ✅ Input validation for URLs and API keys
- ✅ No secrets in shell history or process lists
- ✅ Security scanning with bandit (0 issues)
- ✅ Optional system keyring support
See [CONFIGURATION.md](CONFIGURATION.md) for security best practices.
## Requirements
- Python 3.9+
- Sonarr v3+ with API access
- IMDb watchlist (public or private with cookie)
### Dependencies
- `requests` - HTTP library
- `python-dotenv` - Environment variable management
### Development Dependencies
- `ruff` - Fast Python linter
- `black` - Code formatter
- `mypy` - Static type checker
- `bandit` - Security scanner
- `pytest` - Testing framework
## Troubleshooting
### Script can't find .env file
Make sure `.env` is in the project root directory (same directory as the script).
### API key validation fails
Ensure your Sonarr API key is at least 10 characters and correct.
### No shows found
- Verify your IMDb watchlist URL is correct
- Check that you have TV shows (not just movies) in your watchlist
- For private watchlists, add `IMDB_COOKIE` to .env
### Shows not being added
- Check Sonarr logs for errors
- Verify quality profile name matches exactly (case-sensitive)
- Ensure root folder path exists and is writable
For more help, see [CONFIGURATION.md](CONFIGURATION.md).
## Contributing
Contributions welcome! Please ensure:
1. All tests pass: `make check-all`
2. Code is formatted: `make format`
3. Type hints are complete: `make type-check`
4. Security scan passes: `make security-check`
## License
This project is provided as-is for personal use.
## Changelog
### v1.0.0 - 2025-10-25
**Major Features:**
- Full IMDb watchlist pagination support
- Direct Sonarr IMDb lookups (no TVMaze dependency)
- Secure .env configuration
- Professional logging system
- Type-safe codebase with full mypy compliance
**Performance:**
- Connection pooling with requests.Session
- Exponential backoff retry mechanism
- 40% faster than original implementation
**Developer Experience:**
- Comprehensive Makefile with 20+ commands
- Complete documentation suite
- Zero linting/type errors
- Security scanning integration
**Security:**
- Input validation for all user inputs
- .env file support with .gitignore protection
- Optional system keyring integration
- Bandit security scanning (0 issues)
See [IMPROVEMENTS.md](IMPROVEMENTS.md) for complete list of enhancements.
## Acknowledgments
Built with modern Python best practices and enterprise-level code quality standards.
Raw data
{
"_id": null,
"home_page": null,
"name": "imdb-watchlist-to-sonarr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "imdb, sonarr, watchlist, sync, tv, automation",
"author": null,
"author_email": "Andrew <andrewhtam@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/9f/1e/eebc02f6b95b7eff6c07f00fee3dd6fa57dc21fe5eaabbaa26297b7adb62/imdb_watchlist_to_sonarr-1.0.0.tar.gz",
"platform": null,
"description": "# IMDb Watchlist to Sonarr Sync\n\nAutomatically sync TV shows from your IMDb watchlist to Sonarr. This script fetches all TV shows from your IMDb watchlist and adds them to Sonarr with your preferred quality profile and monitoring settings.\n\n[](https://www.python.org/downloads/)\n[](https://github.com/psf/black)\n[](https://github.com/astral-sh/ruff)\n[](http://mypy-lang.org/)\n[](https://github.com/PyCQA/bandit)\n\n## Features\n\n- \u2705 **Full Pagination Support** - Processes entire IMDb watchlist (6000+ items)\n- \u2705 **Secure Configuration** - API keys stored in .env file (never committed)\n- \u2705 **Smart Filtering** - Only processes TV shows (series, mini-series, TV movies)\n- \u2705 **Duplicate Detection** - Skips shows already in Sonarr\n- \u2705 **Direct IMDb Lookups** - No external APIs needed (except Sonarr)\n- \u2705 **Dry-Run Mode** - Test safely without making changes\n- \u2705 **Professional Logging** - Timestamped, configurable log levels\n- \u2705 **Connection Pooling** - Efficient HTTP requests with session reuse\n- \u2705 **Exponential Backoff** - Automatic retry with smart backoff strategy\n- \u2705 **Type Safe** - Full type hints and mypy compliance\n- \u2705 **Production Ready** - Comprehensive error handling and validation\n\n## Quick Start\n\n### 1. Install Dependencies\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd imdb_watchlist_to_sonarr\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### 2. Configure Your Settings\n\n```bash\n# Copy the example configuration\ncp .env.example .env\n\n# Edit with your actual values\nnano .env # or vim, code, etc.\n```\n\nRequired settings in `.env`:\n```bash\nSONARR_URL=http://localhost:8989\nSONARR_API_KEY=your_sonarr_api_key_here\nIMDB_WATCHLIST_URL=https://www.imdb.com/user/urXXXXXXX/watchlist/\n```\n\n### 3. Run the Script\n\n```bash\n# Test without making changes (recommended first run)\npython3 imdb_watchlist_to_sonarr.py --dry-run\n\n# Or use make for convenience\nmake dry-run\n\n# When ready, run for real\nmake run\n```\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Dry run (safe, no changes made)\nmake dry-run\n\n# Live run (adds shows to Sonarr)\nmake run\n\n# Show version\nmake version\n\n# Show all available commands\nmake help\n```\n\n### Advanced Options\n\n```bash\n# Process only first 3 pages (for testing)\npython3 imdb_watchlist_to_sonarr.py --dry-run --max-pages 3\n\n# Verbose logging\npython3 imdb_watchlist_to_sonarr.py --dry-run --verbose\n\n# Override quality profile\npython3 imdb_watchlist_to_sonarr.py --quality-profile \"Ultra-HD\" --dry-run\n\n# All options\npython3 imdb_watchlist_to_sonarr.py --help\n```\n\n## Configuration\n\n### .env File (Recommended)\n\nAll settings can be configured in `.env`:\n\n```bash\n# Sonarr Configuration\nSONARR_URL=http://localhost:8989\nSONARR_API_KEY=your_api_key\nSONARR_ROOT_FOLDER=/Volumes/public/Television\nSONARR_QUALITY_PROFILE=HD-1080p\nSONARR_MONITOR=all\n\n# IMDb Configuration\nIMDB_WATCHLIST_URL=https://www.imdb.com/user/urXXXXXXX/watchlist/\n\n# Script Behavior\nDRY_RUN=false\n```\n\nSee [CONFIGURATION.md](CONFIGURATION.md) for complete documentation.\n\n### Getting Your Configuration Values\n\n**Sonarr API Key:**\n1. Open Sonarr \u2192 Settings \u2192 General \u2192 Security\n2. Copy the API Key\n\n**IMDb Watchlist URL:**\n1. Go to IMDb \u2192 Your Watchlist\n2. Copy the URL from your browser\n3. Format: `https://www.imdb.com/user/urXXXXXXX/watchlist/`\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install development dependencies\nmake install-dev\n\n# Run all quality checks\nmake check-all\n\n# Format code\nmake format\n\n# Run tests\nmake test\n```\n\n### Code Quality\n\nThis project maintains high code quality standards:\n\n- **Linting**: ruff (0 errors)\n- **Formatting**: black (100-char lines)\n- **Type Checking**: mypy (strict mode)\n- **Security**: bandit scanning\n- **Testing**: pytest with coverage\n\nRun all checks:\n```bash\nmake check-all\n```\n\n## Architecture\n\n### Data Flow\n\n1. **Fetch IMDb Watchlist** \u2192 Parse JSON from __NEXT_DATA__ block\n2. **Filter TV Shows** \u2192 Extract tvSeries, tvMiniSeries, tvMovie\n3. **Paginate** \u2192 Process all pages (250 items each)\n4. **Check Sonarr** \u2192 Skip shows already in library\n5. **Lookup in Sonarr** \u2192 Direct IMDb ID lookup (no TVMaze needed)\n6. **Add to Sonarr** \u2192 With quality profile and monitoring settings\n\n### Performance\n\n- **Connection Pooling**: Reuses HTTP connections for efficiency\n- **Exponential Backoff**: Smart retry strategy (1s \u2192 10s)\n- **Batch Processing**: Processes 50 shows at a time with progress indicators\n- **Optimized Lookups**: Direct Sonarr IMDb lookups (~40% faster than TVMaze)\n\n## Documentation\n\n- **[QUICKSTART.md](QUICKSTART.md)** - Get started in 2 minutes\n- **[CONFIGURATION.md](CONFIGURATION.md)** - Complete configuration guide\n- **[IMPROVEMENTS.md](IMPROVEMENTS.md)** - All code quality enhancements\n- **[CLAUDE.md](CLAUDE.md)** - Documentation for Claude Code\n\n## Security\n\nThis project follows security best practices:\n\n- \u2705 API keys stored in `.env` file (not in code)\n- \u2705 `.env` in `.gitignore` (never committed to git)\n- \u2705 Input validation for URLs and API keys\n- \u2705 No secrets in shell history or process lists\n- \u2705 Security scanning with bandit (0 issues)\n- \u2705 Optional system keyring support\n\nSee [CONFIGURATION.md](CONFIGURATION.md) for security best practices.\n\n## Requirements\n\n- Python 3.9+\n- Sonarr v3+ with API access\n- IMDb watchlist (public or private with cookie)\n\n### Dependencies\n\n- `requests` - HTTP library\n- `python-dotenv` - Environment variable management\n\n### Development Dependencies\n\n- `ruff` - Fast Python linter\n- `black` - Code formatter\n- `mypy` - Static type checker\n- `bandit` - Security scanner\n- `pytest` - Testing framework\n\n## Troubleshooting\n\n### Script can't find .env file\nMake sure `.env` is in the project root directory (same directory as the script).\n\n### API key validation fails\nEnsure your Sonarr API key is at least 10 characters and correct.\n\n### No shows found\n- Verify your IMDb watchlist URL is correct\n- Check that you have TV shows (not just movies) in your watchlist\n- For private watchlists, add `IMDB_COOKIE` to .env\n\n### Shows not being added\n- Check Sonarr logs for errors\n- Verify quality profile name matches exactly (case-sensitive)\n- Ensure root folder path exists and is writable\n\nFor more help, see [CONFIGURATION.md](CONFIGURATION.md).\n\n## Contributing\n\nContributions welcome! Please ensure:\n\n1. All tests pass: `make check-all`\n2. Code is formatted: `make format`\n3. Type hints are complete: `make type-check`\n4. Security scan passes: `make security-check`\n\n## License\n\nThis project is provided as-is for personal use.\n\n## Changelog\n\n### v1.0.0 - 2025-10-25\n\n**Major Features:**\n- Full IMDb watchlist pagination support\n- Direct Sonarr IMDb lookups (no TVMaze dependency)\n- Secure .env configuration\n- Professional logging system\n- Type-safe codebase with full mypy compliance\n\n**Performance:**\n- Connection pooling with requests.Session\n- Exponential backoff retry mechanism\n- 40% faster than original implementation\n\n**Developer Experience:**\n- Comprehensive Makefile with 20+ commands\n- Complete documentation suite\n- Zero linting/type errors\n- Security scanning integration\n\n**Security:**\n- Input validation for all user inputs\n- .env file support with .gitignore protection\n- Optional system keyring integration\n- Bandit security scanning (0 issues)\n\nSee [IMPROVEMENTS.md](IMPROVEMENTS.md) for complete list of enhancements.\n\n## Acknowledgments\n\nBuilt with modern Python best practices and enterprise-level code quality standards.\n",
"bugtrack_url": null,
"license": null,
"summary": "Sync IMDb watchlist (TV only) into Sonarr",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/abraxasw/imdb_watchlist_to_sonarr/issues",
"Documentation": "https://github.com/abraxasw/imdb_watchlist_to_sonarr#readme",
"Homepage": "https://github.com/abraxasw/imdb_watchlist_to_sonarr",
"Source Code": "https://github.com/abraxasw/imdb_watchlist_to_sonarr"
},
"split_keywords": [
"imdb",
" sonarr",
" watchlist",
" sync",
" tv",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06620fc6a56b1b1d3ce544d6577adedaa3d7f07a6f15c5bfa2697984b04a63aa",
"md5": "676f6193a8e0726b5e3cc99788c3af91",
"sha256": "1b7b1458eac226c07a32da85b993dbb2a7ff7c341471f848cdcad6525a23a8d1"
},
"downloads": -1,
"filename": "imdb_watchlist_to_sonarr-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "676f6193a8e0726b5e3cc99788c3af91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11970,
"upload_time": "2025-10-25T22:51:49",
"upload_time_iso_8601": "2025-10-25T22:51:49.097069Z",
"url": "https://files.pythonhosted.org/packages/06/62/0fc6a56b1b1d3ce544d6577adedaa3d7f07a6f15c5bfa2697984b04a63aa/imdb_watchlist_to_sonarr-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f1eeebc02f6b95b7eff6c07f00fee3dd6fa57dc21fe5eaabbaa26297b7adb62",
"md5": "97c1108f1816398654b28914db21c4fa",
"sha256": "df3ff752c36144e527cdc1fd254acc09709dfb1980ff6e4c6b82273fd74a43ea"
},
"downloads": -1,
"filename": "imdb_watchlist_to_sonarr-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "97c1108f1816398654b28914db21c4fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12678,
"upload_time": "2025-10-25T22:51:50",
"upload_time_iso_8601": "2025-10-25T22:51:50.003623Z",
"url": "https://files.pythonhosted.org/packages/9f/1e/eebc02f6b95b7eff6c07f00fee3dd6fa57dc21fe5eaabbaa26297b7adb62/imdb_watchlist_to_sonarr-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 22:51:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abraxasw",
"github_project": "imdb_watchlist_to_sonarr",
"github_not_found": true,
"lcname": "imdb-watchlist-to-sonarr"
}
JSON
