bili-dl

Cross-platform Bilibili downloader — a thin, fast wrapper around yt-dlp + ffmpeg.

Download Bilibili videos and audio at the best available quality (up to 1080p for non-premium accounts). Cross-platform, zero runtime dependencies, foobar2000-friendly audio output.

Features

• Cookie-safe — drop any .txt cookie export next to the tool, and only the Bilibili-domain entries are extracted. Other-site cookies are never parsed, stored, or sent anywhere.
• Cookie-verified — probes Bilibili's nav API to confirm your session is actually logged in before downloading.
• foobar2000-friendly audio — every produced M4A goes through a zero-loss ffmpeg -c copy remux (moov-first + ISOM container). No re-encode, no quality loss, instant playback in picky players.
• Zero runtime deps — standard library only. If you have Python, pipx install bili-dl is all you need.
• Configurable — set defaults in a TOML config file (mode, proxy, output dirs, etc.); CLI flags override per-invocation.
• Batch download — download a list of URLs from a text file.

Install

bili-dl needs yt-dlp and ffmpeg on your PATH:

pip install -U yt-dlp       # or: winget / brew / pipx
# ffmpeg:
winget install ffmpeg        # Windows
brew install ffmpeg          # macOS
sudo apt install ffmpeg      # Debian/Ubuntu

Then:

pipx install bili-dl         # recommended
bili-dl -V                   # verify

Quick start

Cookies (one-time)

Bilibili requires a login cookie. Use any browser extension that exports cookies in Netscape format (Cookie-Editor, Get cookies.txt, etc.):

1. Log in to bilibili.com

2. Export cookies — the file should look like:

   # Netscape HTTP Cookie File
   .bilibili.com	TRUE	/	FALSE	0	SESSDATA	<session>
   .bilibili.com	TRUE	/	FALSE	0	bili_jct	<csrf>
   

3. Save the exported .txt file in the cookie directory (any filename works):

Run bili-dl once — it auto-detects any .txt file containing Bilibili entries, extracts only those, and reuses them thereafter. Override with --cookie-dir.

Download

bili-dl                                       # interactive REPL
bili-dl https://www.bilibili.com/video/BV...   # one-shot (video + audio)
bili-dl -a https://www.bilibili.com/video/BV...  # audio only
bili-dl -v https://www.bilibili.com/video/BV...  # video only
bili-dl --batch-file urls.txt                  # batch: download all URLs in file

Override with --output-dir / --audio-dir.

Config file

Save defaults in config.toml (in the cookie directory shown above) so you don't repeat CLI flags every time:

mode = "a"                      # "all" | "v" | "a"
proxy = "http://127.0.0.1:7890"
insecure = false
video_dir = "/path/to/videos"
audio_dir = "/path/to/audio"
cookie_dir = "/path/to/cookies"

All fields are optional — set only what you need. CLI flags always override config file values. Override the config path with --config FILE.

Batch download

Create a text file with one URL per line (# for comments):

# my playlist
https://www.bilibili.com/video/BV1xx...
https://www.bilibili.com/video/BV2xx...

bili-dl --batch-file urls.txt

CLI reference

Privacy

• Only Bilibili-domain cookie lines are kept; all others are discarded in memory — never written to disk or sent anywhere.
• Network requests go only to api.bilibili.com (login probe) and the URLs you provide (via yt-dlp). No telemetry, no analytics.
• cookies_bilibili.txt is created with a timestamped backup before any overwrite.

Limitations

• Single video only — --no-playlist is always passed, so multi-P videos, collections, and favourites are not downloaded as a batch. Give each part's URL separately (or list them in a --batch-file).
• Batch downloads are sequential — no concurrency. A long URL list takes proportionally longer; this keeps memory low and avoids hammering Bilibili.
• Re-downloading overwrites — no --no-overwrites / --continue is passed to yt-dlp. Running the same URL twice re-downloads and replaces the file.
• Windows CJK filenames — on a stock Windows console (cp936/GBK) titles containing rare characters or emoji may lose those characters in the saved filename. Common Chinese characters are unaffected. This is a deliberate trade-off for reliable path matching (see AGENTS.md §2.9); forcing UTF-8 would silently break downloads instead.

License

MIT. bili-dl is a wrapper; the actual downloading is done by yt-dlp (Unlicense) and ffmpeg (LGPL/GPL), which you must install separately.