BiliDownloader

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

Caution

This tool is provided "as is" for educational purposes only.

No warranties, express or implied, are provided regarding its functionality or suitability for any specific purpose.

The distribution or use of any output generated by this tool for public or commercial purposes is strictly prohibited and strongly discouraged.

The creators and maintainers of this tool disclaim any liability for damages or losses resulting from its use.

Table of Contents

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

Requirements

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

• Python 3.11 or later
• git for cloning the repository
• pipx (install via pip install pipx)
• 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.

Installation

Note

Currently, we only support installation via pipx for better package management. If pipx is not installed, you can install it using pip install pipx or check if your distribution's package manager provides it.

Warning

If you're utilizing pipxu to manage bilidownloader, keep in mind that due to uv's nature, it can not update the app from bare repository without reinstalling it first.

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'

# For Termux users, additional steps may be required:
pkg install x11-repo
pkg install busybox ffmpeg git mkvtoolnix openssl python python-pip
pip install pipx
pip install --extra-index-url "https://termux-user-repository.github.io/pypi/" pydantic
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 track support.

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

Features

• Download episodes
• Retrieve the latest schedule
• Monitor and automatically download episodes for tracked series (watchlist)
• Manage your Favorite List directly from the terminal

Limitations

• Cannot bypass premium restrictions: a premium account is required to download paywalled content
• Does not run in the background: use crontab 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

Usage

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.

Global Options

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

Commands

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

download

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

today

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

Alias: now

bilidownloader today [OPTIONS]

released

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

Alias: rel

bilidownloader released [OPTIONS]

schedule

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

watchlist

Manage your watchlist of series.

Alias: wl

watchlist list

List all series in your watchlist.

Alias: ls, l

bilidownloader watchlist list

watchlist add

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]

watchlist delete

Remove a series from your watchlist.

Alias: del, remove, rm

bilidownloader watchlist delete [SERIES_ID_OR_URL]

watchlist download

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

Alias: down, dl, d

bilidownloader watchlist download

history

Manage your download history.

Alias: his, h

history list

List all downloaded episodes.

Alias: ls, l

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

history query

Search your download history.

Alias: q, search, find

bilidownloader history query <QUERY>

history clear

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>]

Configuration

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.

Cookie File

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.

Watchlist File

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

History File

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

Development and Testing

To test the application, use the following command:

pipx 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.

Versioning

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.

License

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.