https://github.com/Woahai321/list-sync
ListSync automates the import of your IMDB & Trakt lists into Overseerr & Jellyseerr, simplifying your movie management.
https://github.com/Woahai321/list-sync
docker imdb imdb-scraper imdb-webscrapping jellyfin jellyseerr overseerr plex plex-media-server python radarr selenium seleniumbase sonarr trakt trakt-tv webscraping
Last synced: about 2 months ago
JSON representation
ListSync automates the import of your IMDB & Trakt lists into Overseerr & Jellyseerr, simplifying your movie management.
- Host: GitHub
- URL: https://github.com/Woahai321/list-sync
- Owner: Woahai321
- Created: 2024-09-22T19:29:14.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-09T02:17:43.000Z (2 months ago)
- Last Synced: 2025-03-09T02:23:07.871Z (2 months ago)
- Topics: docker, imdb, imdb-scraper, imdb-webscrapping, jellyfin, jellyseerr, overseerr, plex, plex-media-server, python, radarr, selenium, seleniumbase, sonarr, trakt, trakt-tv, webscraping
- Language: Python
- Homepage: https://soluify.com
- Size: 389 KB
- Stars: 118
- Watchers: 2
- Forks: 8
- Open Issues: 7
-
Metadata Files:
- Readme: ReadMe.md
- Contributing: docs/contributing.md
- Funding: .github/FUNDING.yml
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
- awesome-jellyfin - List-Sync ` 🔸 ` - Automatically import movies and TV shows from IMDB or Trakt lists into [Jellyseerr](https://github.com/Fallenbagel/jellyseerr). (👾 Other)
README
# 🍿 ListSync - Bridge Your Watchlist & Media Server 🎬
[](https://soluify.com/)
[](https://www.linkedin.com/company/soluify)
---
## 🚀 What is ListSync?
ListSync automatically syncs your watchlists from IMDb, Trakt, and Letterboxd with Overseerr/Jellyseerr. No more manual adding - just add movies and shows to your favorite watchlist, and they'll appear in your media server automatically.
Key Features:
- 🔄 Automatic synchronization
- 🎬 Support for multiple watchlist platforms
- 🖥️ Compatible with Overseerr and Jellyseerr
- ⚡ Easy setup with Docker
---
## 📚 Quick Links
- [🚀 Installation Guide](#-getting-started)
- [📋 List Setup Guide](#-obtaining-list-ids)
- [🛠️ Troubleshooting](#-troubleshooting)
- [📖 Documentation](docs/)
- [🌉 SeerrBridge Integration](#-seerrbridge-integration)
---
### Currently in Development for v0.6.0
For the most stable experience, use the source code from the latest release [here](https://github.com/Woahai321/list-sync/releases/tag/v0.5.6).
## 🎬 Demo
---
How Does It Work?
ListSync seamlessly syncs your watchlists with your media server in three simple steps:
#### 1. **Fetch Watchlists**
ListSync retrieves your watchlists from **IMDb**, **Trakt** or **Letterboxd** using Selenium web scraping techniques.
#### 2. **Search Media on Media Server**
ListSync searches for each item on your media server (**Overseerr** or **Jellyseerr**) using its API. It handles edge cases like special characters or multiple results for accurate matches.
#### 3. **Request Media**
ListSync checks if the media is already available or requested. If not, it automatically requests the item:
- For **Movies**, it requests the title.
- For **TV Shows**, it requests all available seasons.
Why Use ListSync?
- **Save Time**: Automates adding movies and TV shows to your media server.
- **Stay Organized**: Keeps your media server in sync with your watchlists.
- **Flexible**: Works with IMDb, Trakt, Letterboxd, Overseerr, and Jellyseerr.
- **Customizable**: Set sync intervals to match your preferences.
---
## 🚀 Getting Started
You can run ListSync in two primary modes: **Interactive Mode** and **Automated Mode**.
### 1. **Interactive Mode** (Recommended for Quick Start)
The quickest way to get started is by using our Docker one-liner, which runs ListSync in Interactive Mode. This option will prompt you for all the necessary information during setup:
| Installation Method | Command |
| :-------------------- | :---------------------------------- |
|  | `docker pull ghcr.io/woahai321/list-sync:main && docker run -it --rm -v "$(pwd)/data:/usr/src/app/data" -e TERM=xterm-256color ghcr.io/woahai321/list-sync:main` |
### 2. **Automated Mode** (Preferred for Regular Syncing)
For a seamless experience, you can run ListSync in Automated Mode using a .env file and Docker Compose. This mode eliminates the need for manual inputs each time you run the script by automatically pulling list IDs and configurations from your `.env` file:
Expand for Docker Compose Instructions 🐳
#### Running with Docker Compose
**Create a `.env` file**: Configure your settings in a `.env` file with the following template:
```env
# Overseerr Configuration
OVERSEERR_URL=https://your-overseerr-instance
OVERSEERR_API_KEY=your-api-key-here
OVERSEERR_USER_ID=1
# Set to true for automated mode (recommended for Docker)
AUTOMATED_MODE=false
# Sync interval in hours (default: 24)
SYNC_INTERVAL=24
# Request Quality Profile (true for 4K, false for standard)
OVERSEERR_4K=false
# Lists Configuration (comma-separated)
# Examples:
IMDB_LISTS=ls123456789,ur123456789,top,boxoffice,https://www.imdb.com/list/ls123456789/
TRAKT_LISTS=12345,67890,https://trakt.tv/users/username/lists/listname
LETTERBOXD_LISTS=https://letterboxd.com/username/list/listname/
```
**Create a `docker-compose.yml` file**:
```
version: "3.8"
services:
listsync:
image: ghcr.io/woahai321/list-sync:main
container_name: listsync
environment:
- OVERSEERR_URL=${OVERSEERR_URL}
- OVERSEERR_API_KEY=${OVERSEERR_API_KEY}
- OVERSEERR_USER_ID=${OVERSEERR_USER_ID:-1}
- SYNC_INTERVAL=${SYNC_INTERVAL:-24}
- AUTOMATED_MODE=true
- OVERSEERR_4K=${OVERSEERR_4K:-false}
- IMDB_LISTS=${IMDB_LISTS}
- TRAKT_LISTS=${TRAKT_LISTS}
- LETTERBOXD_LISTS=${LETTERBOXD_LISTS}
volumes:
- ./data:/usr/src/app/data
- ./.env:/usr/src/app/.env
restart: unless-stopped
```
**Run using Docker Compose**:
| Installation Method | Command |
| :----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|  | `docker-compose up` |
This setup will trigger *Automated Mode*, meaning it will automatically pull in the added lists based on your configuration, streamlining the syncing process.
### 3. **Manual Installation** (Advanced Users)
You can also set up ListSync manually if you prefer a more hands-on approach:
Expand for Manual Installation Instructions 🛠️
#### Manual Installation Methods
| Installation Method | Command |
| :------------------ | :------------------------------------------------------------ |
|  | `git clone https://github.com/Woahai321/list-sync.git && cd list-sync && poetry install && poetry run python add.py` |
|  | `git clone https://github.com/Woahai321/list-sync.git && cd list-sync && pip install -r requirements.txt && python add.py` |
Refer to our [Installation Guide](/docs/installation.md) for detailed instructions.
---
## 📊 Compatibility
### 🌉 SeerrBridge Integration
[](https://github.com/Woahai321/SeerrBridge)
SeerrBridge is our companion application that provides an alternative to traditional \*arr stack (Radarr/Sonarr) setup. It works alongside ListSync to create a complete media management solution:
- **Automated Processing**: When ListSync adds requests to Jellyseerr/Overseerr, SeerrBridge automatically processes them
- **Browser Automation**: Uses Selenium to automate media fetching through Debrid Media Manager
- **Simplified Setup**: Eliminates the need for complex \*arr stack configuration
- **Real-Debrid Integration**: Direct integration with Real-Debrid for content retrieval
#### How ListSync & SeerrBridge Work Together
1. ListSync adds media requests to Jellyseerr/Overseerr
2. SeerrBridge detects the requests via webhook
3. SeerrBridge automatically processes the requests through DMM
4. Media becomes available in your library
For detailed information about SeerrBridge, visit the [SeerrBridge Repository](https://github.com/Woahai321/SeerrBridge).
### Media Server Compatibility
| Application | Status | Notes |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------: | :--------------------------------- |
|  | ✅ Supported | Full functionality with Overseerr |
|  | ✅ Supported | Full functionality with Jellyseerr |
|  | ✅ Supported | Compatible through Jellyseerr |
|  | ✅ Supported | Compatible through Jellyseerr |
### Supported List Services
| Service | Status | Notes |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------: | :------------------ |
|  | ✅ Supported | Currently supported |
|  | ✅ Supported | Currently supported |
|  | ✅ Supported | Currently supported |
---
## 📋 Obtaining List IDs
ListSync supports **IMDb**, **Trakt**, and **Letterboxd** lists. You can add them using either the raw URL or the list ID.
📋 IMDb List ID or URL
#### **Using the Raw URL**:
1. Navigate to your IMDb list in your browser.
2. Copy the URL from the address bar. Examples:
- Custom lists: `https://www.imdb.com/list/ls012345678/`
- IMDb charts: `https://www.imdb.com/chart/top/` (Top 250), `https://www.imdb.com/chart/boxoffice/` (Box Office)
- Watchlists: `https://www.imdb.com/user/ur12345678/watchlist`
3. Paste the URL directly into ListSync.
#### **Using the List ID**:
1. Look at the URL:
- Custom lists: `ls012345678`
- IMDb charts: Use the chart name (e.g., `top`, `boxoffice`)
- Watchlists: `ur12345678`
2. Use the list ID in ListSync.
#### **Supported IMDb Charts**:
- `top` (Top 250 Movies)
- `boxoffice` (Box Office)
- `moviemeter` (MovieMeter)
- `tvmeter` (TVMeter)
📋 Trakt List ID or URL
#### **Using the Raw URL**:
1. Navigate to your Trakt list in your browser.
2. Copy the URL from the address bar. Example:
- `https://trakt.tv/users/username/lists/example-list`
3. Paste the URL directly into ListSync.
#### **Using the List ID**:
1. Click the "Share" button on your Trakt list.
2. Copy the link, which will look like:
- `https://trakt.tv/lists/12345678`
3. The list ID is the number at the end (e.g., `12345678`).
📋 Letterboxd URL
#### **Using the Raw URL**:
1. Navigate to your Letterboxd list in your browser.
2. Copy the URL from the address bar. Example:
- `https://letterboxd.com/user/list/example-list/`
3. Paste the URL directly into ListSync.
### Adding Multiple List IDs
When inputting list IDs or URLs, you can add multiple lists by separating them with commas:
- Example: `ls012345678,12345678,https://www.imdb.com/chart/top/,ur987654321,https://letterboxd.com/user/list/example-list/`
This allows you to sync multiple lists at once, whether they are custom lists, charts, or watchlists.
---
## 📋 Notes
- **Security Best Practices:** Please read scripts you find online before running them.
- **API Credentials:** Always keep your API credentials secure.
- **Rate Limiting:** Be mindful of Overseerr's rate limiting policies during imports.
- **Permissions:** Only import and manage media you have the rights to handle.
## 💰 Donations
If you find ListSync useful and would like to support its development, consider making a donation:
- BTC (Bitcoin): `bc1qxjpfszwvy3ty33weu6tjkr394uq30jwkysp4x0`
- ETH (Ethereum): `0xAF3ADE79B7304784049D200ea50352D1C717d7f2`
Thank you for your support!
---
## 🔎 How it Works
For detailed information on how ListSync works, please refer to our [How it Works](/docs/how-it-works.md) document.
## 🛠 Troubleshooting
If you encounter any issues while using ListSync, please check our [Troubleshooting Guide](/docs/troubleshooting.md) for solutions to common problems.
## 🛤️ Roadmap
To see our plans for future development and features, visit our [Roadmap](/docs/roadmap.md).
## 🤝 Contributing
We welcome contributions! For guidelines on how to contribute, please see our [Contributing Guide](/docs/contributing.md).
## 📄 License
This project is licensed under the [MIT License](https://opensource.org/license/mit). Review the LICENSE file for more details.
## 🛡️ Legal Disclaimer
For important legal information about using ListSync, please refer to our [Legal Disclaimer](/docs/legal-disclaimer.md).
## Star History
[](https://star-history.com/#Woahai321/list-sync&Date)