wco-dl

A command-line and web-based tool to download cartoons, anime, and movies from WCOStream.

Downloading and distributing this content may be illegal. This script was written for educational purposes purely and you are responsible for its use.

Support these streaming websites by buying a premium account and registering!

Features

• Download single episodes or entire series
• Search for shows by name
• Season and episode range filtering
• Exclude episodes by keyword
• Multi-threaded downloads
• 1080p HLS streaming support
• Download progress with tqdm (CLI) and progress bar (Web UI)
• Local database tracking of downloaded shows/episodes
• Web UI with Gradio for easy browser-based usage
• Docker support for self-hosting (e.g. Unraid)

Requirements

• Python 3.13+
• uv (recommended package manager)
• ffmpeg (for HLS downloads)

Installation

# Clone the repository
git clone https://github.com/EpicUnknown/wco-dl.git
cd wco-dl

# Install dependencies with uv
uv sync

# Install Playwright browser
uv run playwright install chromium

CLI Usage

uv run main.py [OPTIONS]

Options

Flag	Description	Default
-u, --urls	URLs to download	—
-x, --exclude	Exclude episodes containing these strings	—
-l, --lookup	Search for a show by name	—
-t, --threads	Number of download threads	1
-s, --season	Download a specific season (0 = all)	0
-r, --range	Episode range (e.g. 1, 1-10, 1-)	all
-n, --dry-run	Do everything except download	False
-d, --database	Show all downloaded shows	False
--database-show	Show all downloaded shows and episodes	False
-V, --version	Print version and exit	—

Examples

# Download a single episode
uv run main.py -u "https://www.wcostream.tv/american-dad-season-7-episode-1-100-a-d"

# Download an entire series
uv run main.py -u "https://www.wcostream.tv/anime/cool-show-name-here"

# Search for a show and download
uv run main.py -l "american dad"

# Download only season 2
uv run main.py -u "https://www.wcostream.tv/anime/cool-show-name-here" -s 2

# Download episodes 1-10
uv run main.py -u "https://www.wcostream.tv/anime/cool-show-name-here" -r 1-10

# Download season 2, episode 5 only
uv run main.py -u "https://www.wcostream.tv/anime/cool-show-name-here" -s 2 -r 5

# Exclude episodes containing "dub"
uv run main.py -u "https://www.wcostream.tv/anime/cool-show-name-here" -x dub

# Dry run (show what would be downloaded)
uv run main.py -u "https://www.wcostream.tv/anime/cool-show-name-here" -n

# Show download history
uv run main.py -d

Web UI

The web UI provides a browser-based interface for searching, browsing, and downloading episodes.

uv run web.py

Then open http://localhost:7860 in your browser.

Features:

• Paste an episode URL, series URL, or search by name
• Browse and filter episodes by season
• Select individual episodes or entire seasons
• Download progress bar with abort/force-abort controls
• Collapsible episode list sorted by season and episode number

Docker

Building

docker build -t wco:v$(uv version --short) -t wco:latest .

Running

docker run -d \
  --name wco-dl \
  -p 7860:7860 \
  -v ./downloads:/downloads \
  -v wco-config:/root/.config/wco \
  wco:latest

Docker Compose

docker compose up -d

The default docker-compose.yml maps:

• Port 7860 for the web UI
• ./downloads volume for downloaded files
• wco-config volume for the database and configuration

Environment Variables

Variable	Description	Default
WCO_DOWNLOAD_DIR	Directory for downloaded files	./downloads

Opening An Issue / Requesting A Feature

Reporting Issues

Run the command with the --verbose argument to generate an error log, then include:

• Subject: The error you get
• Command: The full command you ran
• Error Log: Upload to a Gist/Pastebin and share the link
• Description: What happened vs. what you expected

Suggesting A Feature

• Subject: Brief description of the feature
• Description: Detailed explanation of what you want and how it should work