BiliX

Bilibili 视频下载器，提供命令行及 PySide6 图形界面，支持扫码登录、批量与多 P 下载、清晰度/编码/音轨选择，以及下载后的媒体校验。

项目主页 · GitHub · PyPI · Windows 下载 · 更新记录

项目状态

本轮源码与发行材料版本为 1.7.0，新增会话任务历史、精确快照重试、逐来源选集、冲突预览、配置来源与安装升级保护；实际结果和本轮接受的未验证范围见验收记录。正式文件与渠道状态以 v1.7.0 发行页 为准。

图形版自 1.6.0 起提供 Windows 10 x64 单文件绿色版、安装版，以及 Ubuntu 22.04/24.04、Debian 12/13 amd64 的 .deb。CLI 保留 1.5.0 增加的 Tab 补全与相近指令提示。1.7.0 的安装升级与真实媒体检查已完成，真实桌面 IME/DPI 等范围仍未验证；历史首版文件保留在 v1.6.0 发行页。

Python 包要求 3.11 或更新版本。Windows GUI/CLI 独立程序和 Linux deb 无需安装 Python/Qt；Windows 包内置 FFmpeg，deb 自动安装系统 FFmpeg 依赖。macOS 暂提供 CLI Python 包，GUI 支持后续加入。

安装

安装命令行 Python 版本：

uv tool install djhx-bilix
blx --help

也可使用 pip install djhx-bilix。blx 与 bilix 为同一程序的两个命令名；模块入口为 python -m djhx_bilix。更新运行 uv tool upgrade djhx-bilix。

Windows 从 GitHub Releases 下载，并按发行页的 SHA256 校验文件。GUI 绿色版直接运行 EXE，同时保存配套许可证与源码 ZIP；安装版运行 Setup EXE。CLI 解压 ZIP 后，在 PowerShell 当前目录使用 ./bilix.exe。

Ubuntu/Debian GUI 安装下载的 deb：

sudo apt install ./djhx-bilix-gui_1.7.0-1_amd64.deb
bilix-gui

也可使用 uv tool install 'djhx-bilix[gui]' 或 pip install 'djhx-bilix[gui]' 安装 GUI，然后运行 bilix-gui。Python 方式需自行安装 FFmpeg 并加入 PATH，或在 GUI 设置/CLI --ffmpeg 中指定路径。

从源码开发或运行 GUI：

uv sync --locked --extra gui --group gui-test
uv run --locked --extra gui bilix-gui

GUI 与 CLI 共用下载内核、账号和配置。功能流程见图形版使用说明，源码构建发行文件见GUI 构建与发行。首版使用手动升级：绿色版退出后替换 EXE，安装版运行新安装器，deb 通过 apt 安装新包；用户配置与下载文件独立保存。

首版的完成情况、最终产物和当时未验证的范围见 1.6.0 验收记录。1.7.0 的真实账号、稳定版升级与桌面补测结果独立记录在本轮验收记录；后续范围见 CLI/GUI 开发路线。

快速开始

blx auth login
blx auth status
blx info BV1j4411W7F7
blx download BV1j4411W7F7 --dry-run
blx download BV1j4411W7F7 --save videos -q 1080p

用手机 Bilibili App 扫码并确认；凭据保存在用户配置目录。默认选择当前账号实际可获取的最高视频清晰度与 AAC 音轨。清晰度/编码不可用时提示降级；要求精确匹配时使用 --strict。

blx download BV12R4y1J75d --page 1,3,5-7
blx download --file videos.txt --quiet
blx download BV1j4411W7F7 --codec HEVC --audio best
blx config
blx doctor

多 P 默认选择全部，含 ?p=2 的链接默认选择 P2；--page 优先于链接。批量文件每行一个 URL/BV 号，支持 UTF-8/BOM、空行与 # 注释。

已有同名文件默认跳过；--overwrite 在新文件完成下载、校验与合并后才替换旧文件。失败保留 .bilix-* 临时材料，返回非零退出码。详细参数见 blx download --help 与 用法说明。

终端体验

1.5.0 支持 Bash、Zsh、Fish、Windows PowerShell 5.1 与 PowerShell 7 的 Tab 补全，覆盖命令、参数、清晰度、编码、音轨和本地路径。PowerShell 当前会话可这样启用：

blx completion powershell | Out-String | Invoke-Expression

blx donwload 会提示相近的 download，参数解析错误返回退出码 2。启用方式、持久配置与排错见 补全说明。

文档

项目页面源码为 site/bilix.html，沿用线上布局与背景图，更新当前命令说明。CSS、背景图与脚本内嵌，无需构建；版本查询失败时仍保留发行页链接。发布时复制到现有网站的 /project/bilix.html，见 页面维护说明。

开发

uv sync --locked
uv run blx --help
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run pytest -q

GUI 测试需要 uv sync --locked --extra gui --group gui-test；无桌面的环境可设置 QT_QPA_PLATFORM=offscreen。GUI 发行文件依目标平台分别构建，不把 Windows 编译结果当作 Linux 验证。

统一检查入口为 uv run --locked python scripts/validate.py --profile cli；GUI 环境使用 uv run --locked --extra gui --group gui-test python scripts/validate.py --profile gui。每轮生成独立日志与 JSON/XML 结果，缺少 GUI 测试依赖会失败；完整平台及发布验收按测试规范执行。

唯一业务实现位于 src/djhx_bilix。项目使用本地检查与手动发布，不运行 GitHub/Gitea Actions。发布前须完成 发布说明 中的凭据、源码与产物检查。

许可与使用边界

项目采用 GPL-3.0-only，使用、修改与再分发遵循其条款。软件许可与视频内容的版权、平台授权属于不同事项。

仅下载你拥有访问与保存权限的内容，遵守所在地法律、版权要求与平台条款。程序不绕过账号权限、单独购买权限或 DRM；试看媒体明确拒绝下载。软件按许可证提供，不作担保。

扫码凭据、Cookie、二维码链接与签名媒体地址不应出现在公开问题、日志或提交中。见 安全政策。

致谢

项目参考了 Bilibili API 资料、BBDown 和 早期实现。原图标保存在 docs/assets。本项目并非 Bilibili 官方产品。