yt-dlp Wrapper & Extension for BiliBili.tv to assist you in ripping episode

• BiliDownloader
  • Table of Contents
  • Requirements
  • Installation
  • Features
  • Limitations
  • Usage
    • Global Options
  • Commands
    • download
    • today
    • released
    • schedule
    • userdir
    • watchlist
      • watchlist list
      • watchlist add
      • watchlist delete
      • watchlist download
    • history
      • history list
      • history query
      • history clear
      • history stats
  • Configuration
    • Cookie File
    • Watchlist File
    • History File
  • Development and Testing
  • Versioning
  • License

Ensure the following libraries/programs are installed before using this tool:

• Python 3.11 or later (up to 3.13)
• git for cloning the repository
• pipx or pipxu (install via pip install pipx or pip install pipxu)
  • Note: pipxu uses uv under the hood for faster installation
• The latest version of FFmpeg, available in your system's PATH
• MKVToolNix (non-containerized versions only, such as Flatpak or Snap are not supported), with mkvpropedit accessible from the bundle

Additionally, you must obtain your own cookie.txt from BiliIntl, and ensure that Premium is activated.

Using pipx:

pipx install git+https://github.com/nattadasu/bilidownloader.git

# To enable ASS subtitle support, use the following command instead:
# Note: Depending on your device, installation may take anywhere from a few minutes to an hour.
pipx install 'bilidownloader[ass] @ git+https://github.com/nattadasu/bilidownloader.git'

Using pipxu (faster installation):

pipxu install git+https://github.com/nattadasu/bilidownloader.git

# To enable ASS subtitle support:
pipxu install 'bilidownloader[ass] @ git+https://github.com/nattadasu/bilidownloader.git'

For Termux users:

# Install required packages
pkg install x11-repo
pkg install busybox ffmpeg git mkvtoolnix openssl python python-pip rust

# Install pipx
pip install pipx

# Install pydantic from Termux repository
pip install --extra-index-url "https://termux-user-repository.github.io/pypi/" pydantic

# Install bilidownloader
pipx install --system-site-packages git+https://github.com/nattadasu/bilidownloader.git

Starting from version 2.1.0, dependencies for ASS subtitle support have been made optional to ensure compatibility with headless devices and non-x86 architectures. This change eliminates the need for compiling dependencies but sacrifices ASS subtitle processing support.

For Termux users, it is not recommended to install the [ass] extra unless you are confident in managing the additional unwritten requirements and troubleshooting steps.

• Download individual episodes or entire series
• Retrieve the latest release schedule
• Monitor and automatically download episodes for tracked series (watchlist)
• Manage your watchlist directly from the terminal
• Track download history with search and statistics
• Desktop notifications for completed downloads

• Cannot bypass premium restrictions: a premium account is required to download paywalled content
• Does not run in the background: use crontab, systemd.timer or a task scheduler to automate periodic execution.
• Cannot download user-uploaded content: the tool is specifically designed for episode URLs
• Does not support the Mainland version: it is tested only with the International version
• Does not automatically organize episodes into folders: use tools like FileBot for this purpose

Run bilidownloader from your terminal. The program uses Typer to build its CLI, so all commands and options are automatically well-documented. Use the --help parameter for more details.

• --help: Show help for commands and subcommands.

Many commands have aliases for ease of use (e.g., dl for download, ls for list).

Download a video or an entire series from a BiliBili URL.

Alias: down, dl, d

bilidownloader download <URL> [OPTIONS]

Example:

bilidownloader download "https://www.bilibili.tv/en/play/2090603/12688293" --resolution 1080

Shows a list of anime released today, allowing you to select one to download.

Alias: now

bilidownloader today [OPTIONS]

Shows a list of anime released in the past three days for you to select and download.

Alias: rel

bilidownloader released [OPTIONS]

Displays the release schedule for the week. You can filter by a specific day.

Alias: calendar, cal, sch, timetable, tt

bilidownloader schedule [--day <DAY>]

Example:

bilidownloader schedule --day monday

Open the user data directory in your file manager, spawn a shell in the directory, or print the path for use with the cd command.

Alias: cfgd, config-dir

bilidownloader userdir [OPTIONS]

Options:

• --cd: Launch a new shell session in the user data directory
  • Automatically detects your current shell from environment variables, Starship config if any, or parent process
  • Supports: nu, elvish, xonsh, fish, zsh, bash, pwsh, and more
• --show, -s: Print the directory path for use with command substitution

Examples:

# Open the user data directory in your file manager (default)
bilidownloader userdir

# Launch a shell in the user data directory
bilidownloader userdir --cd
# Your current shell (fish, bash, zsh, etc.) will be detected automatically
# Type 'exit' to return to the previous shell

# Print the path for command substitution (Unix/Linux/macOS)
cd $(bilidownloader userdir --show)

# Print the path for command substitution (Windows PowerShell)
cd (bilidownloader userdir --show)

# Using aliases
bilidownloader config --cd
bilidownloader config-dir --show

Manage your watchlist of series.

Alias: wl

List all series in your watchlist.

Alias: ls, l

bilidownloader watchlist list

Add a series to your watchlist. You can provide a series URL or ID. If none is provided, an interactive prompt will be shown.

Alias: insert, ins

bilidownloader watchlist add [SERIES_ID_OR_URL]

Remove a series from your watchlist.

Alias: del, remove, rm

bilidownloader watchlist delete [SERIES_ID_OR_URL]

Download all newly released episodes from the series in your watchlist.

Alias: down, dl, d

bilidownloader watchlist download [OPTIONS]

Manage your download history.

Alias: his, h

List all downloaded episodes.

Alias: ls, l

bilidownloader history list [--sort-by <FIELD>]

Search your download history.

Alias: q, search, find

bilidownloader history query <QUERY>

Clear your download history. You can clear all history, or clear by series, date, or episode.

Alias: clean, purge, cls, del, rm

bilidownloader history clear [--by-series <SERIES>] [--by-date <DATE>] [--by-episode <EPISODE_ID>]

Show download history statistics including total episodes downloaded and series statistics.

Alias: statistics, info

bilidownloader history stats

The tool uses three main files to store your data: cookie.txt, watchlist.txt, and history.v2.tsv. By default, these files are located in the appropriate user data directory for your operating system. You can override the location of these files using the --cookie, --watchlist, and --history options.

You must provide a cookie.txt file from BiliBili to download premium content. You can specify the path to your cookie file using the --cookie option.

To obtain cookies, depending on browser you're using:

1. Install Get cookies.txt LOCALLY extension on Chrome/Chromium-based browsers, or cookies.txt on Firefox
2. Open https://bilibili.tv, and make sure you've signed in and premium activated
3. Click the extension icon and export cookies ONLY for bilibili.tv domain
4. Save the exported cookies.txt to BiliDownloader's user data directory or a custom location
   • If saved elsewhere, specify the path using --cookie option when running commands
   • Else, you can open the user data directory using bilidownloader userdir command

Your watchlist is stored in watchlist.txt. This file contains the series IDs and titles of the shows you are monitoring.

Your download history is stored in history.v2.tsv. This file logs every episode you download, preventing duplicate downloads.

To test the application locally, clone the repository and install it in a separate environment:

# Clone the repository
git clone https://github.com/nattadasu/bilidownloader.git
cd bilidownloader

# Install in a test environment
pipx install --suffix "_test" ".[ass]"

# Or use pipxu for faster installation
pipxu install --suffix "_test" ".[ass]"

This installs the package with the [ass] extra in a separate environment, allowing you to test without affecting your main installation. The test version will be available as bilidownloader_test.

BiliDownloader follows Semantic Versioning.

Each release is tagged with a version number in the format vX.Y.Z, where:

• X represents major versions with breaking changes
• Y represents minor versions with new features and backward-compatible changes
• Z represents patch versions with bug fixes or general improvements

Note: Version tags are not applied to the repository itself. Refer to the commit history for detailed information about changes.

This repository is licensed under the GNU General Public License, version 3.0 or later (GPL-3.0-or-later).

You may redistribute and/or modify the contents of this repository under the terms of the GPL-3.0-or-later.

A copy of the license is available in the LICENSE file or at https://www.gnu.org/licenses/gpl-3.0.html.