XHS-Downloader README

The project's README from github.com/JoeanAmier/XHS-Downloader. As one markdown file: README.md.

XHS-Downloader

XHS-Downloader

简体中文 | English

JoeanAmier%2FXHS-Downloader | Trendshift
GitHub GitHub forks GitHub Repo stars GitHub code size in bytes GitHub release (with filter)
Static Badge Static Badge Static Badge GitHub all releases

🔥 小红书（XiaoHongShu、RedNote）链接提取/作品采集工具！

📑 项目功能

项目程序与用户脚本功能清单，快速了解项目能力（点击展开）
    程序功能
  • ✅ 采集小红书作品信息
  • ✅ 提取小红书作品下载地址
  • ✅ 下载小红书作品文件
  • ✅ 下载视频作品封面文件
  • ✅ 下载小红书 livePhoto 文件
  • ✅ 自动跳过已下载的作品文件
  • ✅ 作品文件完整性处理机制
  • ✅ 自定义图文作品文件下载格式
  • ✅ 持久化储存作品信息至文件
  • ✅ 作品文件储存至单独文件夹
  • ✅ 后台监听剪贴板下载作品
  • ✅ 记录已下载作品 ID
  • ✅ 支持命令行下载作品文件
  • ☑️ 从浏览器读取 Cookie
  • ✅ 自定义文件名称格式
  • ✅ 支持 API 调用功能
  • ✅ 支持 MCP 调用功能
  • ✅ 支持文件断点续传下载
  • ✅ 智能识别作品文件类型
  • ✅ 支持设置作者备注
  • ✅ 自动更新作者昵称
    脚本功能
  • ✅ 下载小红书作品文件
  • ✅ 提取推荐页面作品链接
  • ✅ 提取账号发布作品链接
  • ✅ 提取账号收藏作品链接
  • ✅ 提取账号点赞作品链接
  • ✅ 提取账号专辑作品链接
  • ✅ 提取搜索结果作品链接
  • ✅ 提取搜索结果用户链接

📸 程序截图

前往 bilibili 观看演示；前往 YouTube 观看演示

GUI 界面截图

TUI 界面截图（模式命令：python .\main.py TUI）

🔗 支持链接

🥣 使用方法

如果仅需下载作品文件，建议选择 程序运行 或 Docker 运行；如果有其他需求，建议选择 源码运行！

⚠️ Cookie 配置为非强制项；如遇功能异常，建议配置或更新 Cookie 后再次尝试！

⚠️ 未设置 Cookie 时，视频作品只能下载低分辨率文件；建议配置 Cookie 以获取更高画质（无需登录账号）！

🖱 程序运行

⭐ Mac OS、Windows 10 及以上用户可前往 Releases 或者 Actions 下载程序压缩包，解压后打开程序文件夹，双击运行 main 即可使用。

⭐ 本项目包含自动构建可执行文件的 GitHub Actions，使用者可以随时使用 GitHub Actions 将最新源码构建为可执行文件！

⭐ 自动构建可执行文件教程请查阅本文档的 构建可执行文件指南 部分；如果需要更加详细的图文教程，请 查阅文章！

注意：由于 Mac OS 平台的可执行文件 main 未经过代码签名，首次运行时会受到系统安全限制。请先在终端执行 xattr -cr 项目文件夹路径 命令移除安全标记，执行一次后即可正常运行。

若通过此方式使用程序，文件默认下载路径为：.\Volume\Download；配置文件路径为：.\Volume\settings.json

程序更新

方案一：下载并解压文件，将旧版本的 Volume 文件夹复制到新版本的程序根目录。

方案二：下载并解压文件（不要运行程序），复制全部文件，直接覆盖旧版本文件。

⌨️ 源码运行

  1. 安装不低于 3.12 版本的 Python 解释器
  2. 下载最新的源码或 Releases 发布的源码至本地
      3. 使用 pip 安装项目依赖
    1. 运行 python -m venv venv 命令创建虚拟环境（可选）
    2. 运行 .\venv\Scripts\activate.ps1 或者 venv\Scripts\activate 命令激活虚拟环境（可选）
    3. 运行 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt 命令安装程序所需模块
    4. 运行 python .\main.py 或者 python main.py 命令启动 XHS-Downloader
      使用 uv 安装项目依赖（推荐）
    1. 运行 uv sync --no-dev 命令同步环境依赖
    2. 运行 uv run main.py 命令启动 XHS-Downloader

⌨️ Docker 运行

  1. 获取镜像
    • 方式一：使用 Dockerfile 文件构建镜像
    • 方式二：使用 docker pull joeanamier/xhs-downloader 命令拉取镜像
    • 方式三：使用 docker pull ghcr.io/joeanamier/xhs-downloader 命令拉取镜像
  2. 创建容器
    • TUI 模式：docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it <镜像名称>
    • API 模式：docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it <镜像名称> python main.py api
    • MCP 模式：docker run --name 容器名称(可选) -p 主机端口号:5556 -v xhs_downloader_volume:/app/Volume -it <镜像名称> python main.py mcp

      • 注意：此处的 <镜像名称> 需与您在第一步中使用的镜像名称保持一致（joeanamier/xhs-downloader 或 ghcr.io/joeanamier/xhs-downloader）
  3. 运行容器
    • 启动容器：docker start -i 容器名称/容器 ID
    • 重启容器：docker restart -i 容器名称/容器 ID

Docker 运行项目时不支持 命令行调用模式，无法使用 读取剪贴板 与 监听剪贴板 功能，可以正常粘贴内容，其他功能如有异常请反馈！

🛠 命令行模式

命令行模式说明，适合习惯命令行操作或需要脚本化调用的用户（点击展开）

项目支持命令行运行模式，可通过命令行参数直接下载作品文件，也可以设置需要下载的图片序号！

注意：未设置 --index 参数时，支持传入多个作品链接，全部链接需要使用引号包围，链接之间使用空格分隔；已设置 --index 参数时，不支持传入多个作品链接，即使传入多个作品链接，程序仅处理首个作品链接！

bool 类型参数支持使用 true、false、1、0、yes、no、on 或 off（不区分大小写）来设置。

从浏览器读取 Cookie

该功能已失效，请参考 获取 Cookie 教程！

可以使用命令行实现 从浏览器读取 Cookie 并写入配置文件！

命令示例：python .\main.py --browser_cookie Chrome --update_settings

兼容性提醒：此功能依赖的第三方模块已长期未更新，可能无法正常支持最新浏览器版本。若功能出现异常，请尝试手动获取 Cookie！

🖥 服务器模式

服务器模式包含 API 模式和 MCP 模式！

API 模式

API 模式说明，适合需要调用接口获取作品数据或下载文件的开发者（点击展开）

启动：运行命令：python .\main.py api

关闭：按下 Ctrl + C 关闭服务器

访问 http://127.0.0.1:5556/docs 或者 http://127.0.0.1:5556/redoc；你会看到自动生成的交互式 API 文档！

请求接口：/xhs/detail

请求方法：POST

请求格式：JSON

请求参数：

参数 类型 含义 默认值
url str 小红书作品链接，自动提取，不支持多链接；必需参数 无
download bool 是否下载作品文件；设置为 true 将会耗费更多时间；可选参数 false
index list[int] 下载指定序号的图片文件，仅对图文作品生效；download 参数设置为 false 时不生效；可选参数 null
cookie str 请求数据时使用的 Cookie；可选参数 配置文件 cookie 参数
proxy str 请求数据时使用的代理；可选参数 配置文件 proxy 参数
check_record bool 是否跳过已有下载记录的作品；可选参数 true

代码示例：

async def example_api():
    """通过 API 设置参数，适合二次开发"""
    server = "http://127.0.0.1:5556/xhs/detail"
    data = {
        "url": "",  # 必需参数
        "download": True,
        "index": [
            3,
            6,
            9,
        ],
        "proxy": "http://127.0.0.1:10808",
    }
    response = post(server, json=data, timeout=10)
    print(response.json())

MCP 模式

MCP 模式说明，适合需要启动 MCP 服务接入 AI 助手等工具的开发者（点击展开）

启动：运行命令：python .\main.py mcp

关闭：按下 Ctrl + C 关闭服务器

MCP 配置示例

Streamable HTTP

MCP URL：http://127.0.0.1:5556/mcp/

MCP配置示例

MCP 调用示例

获取小红书作品信息

MCP获取数据

下载小红书作品文件

下载图文作品时可以指定需要下载的图片序号；默认不返回作品信息，如需返回作品信息，请在对话时明确表述。

MCP下载文件
MCP下载文件

📜 其他说明

🕹 用户脚本

如果您的浏览器安装了 Tampermonkey 浏览器扩展程序，可以使用用户脚本体验项目功能！

用户脚本链接（右键单击复制链接）：master 分支、develop 分支

查看 Tampermonkey 用户脚本截图（点击展开）

提示：使用 XHS-Downloader 用户脚本批量提取作品链接，搭配 XHS-Downloader 程序可以实现批量下载作品文件！

修改用户脚本语言

切换语言

🌏 连接服务器

⭐ 本项目支持通过浏览器用户脚本与主程序联动，实现一键推送下载任务。

📜 脚本说明

自动滚动页面功能代码已重构，该功能默认关闭！启用该功能可能会被小红书检测为自动化操作，从而导致账号受到风控或封禁风险！

💻 二次开发

二次开发代码示例，适合基于项目进行二次开发的开发者（点击展开）

如果有其他需求，可以根据 example.py 的注释提示进行代码调用或修改！

async def example():
    """通过代码设置参数，适合二次开发"""
    # 示例链接
    demo_link = "https://www.xiaohongshu.com/explore/XXX?xsec_token=XXX"
    # 实例对象
    work_path = "D:\\"  # 作品数据/文件保存根路径，默认值：项目根路径
    folder_name = "Download"  # 作品文件储存文件夹名称（自动创建），默认值：Download
    name_format = "作品标题 作品描述"
    impersonate = "chrome146"  # 浏览器模拟目标
    cookie = ""  # 小红书网页版 Cookie
    proxy = None  # 网络代理
    proxy_download = False  # 下载文件时，是否使用 proxy 参数的网络代理
    timeout = 5  # 请求数据超时限制，单位：秒
    chunk = 1024 * 1024 * 10  # 下载文件时，每次从服务器获取的数据块大小，单位：字节
    max_retry = 2  # 请求数据失败时，重试的最大次数，单位：次
    record_data = False  # 是否保存作品数据至文件
    image_format = "WEBP"  # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
    folder_mode = False  # 是否将每个作品的文件储存至单独的文件夹
    image_download = True  # 图文、图集作品文件下载开关
    video_download = True  # 视频作品文件下载开关
    video_cover_download = False  # 视频作品封面文件下载开关
    live_download = False  # 图文动图文件下载开关
    download_record = True  # 是否记录下载成功的作品 ID
    language = "zh_CN"  # 设置程序提示语言
    author_archive = True  # 是否将每个作者的作品存至单独的文件夹
    write_mtime = True  # 是否将作品文件的 修改时间 修改为作品的发布时间
    note_format = ""  # 作品信息保存格式，支持：txt、md、all，为空则不保存
    # read_cookie = None  # 读取浏览器 Cookie，支持设置浏览器名称（字符串）或者浏览器序号（整数），设置为 None 代表不读取
    # async with XHS() as xhs:
    #     pass  # 使用默认参数
    async with XHS(
        work_path=work_path,
        folder_name=folder_name,
        name_format=name_format,
        impersonate=impersonate,
        cookie=cookie,
        proxy=proxy,
        proxy_download=proxy_download,
        timeout=timeout,
        chunk=chunk,
        max_retry=max_retry,
        record_data=record_data,
        image_format=image_format,
        folder_mode=folder_mode,
        image_download=image_download,
        video_download=video_download,
        video_cover_download=video_cover_download,
        live_download=live_download,
        download_record=download_record,
        language=language,
        # read_cookie=read_cookie,
        author_archive=author_archive,
        write_mtime=write_mtime,
        note_format=note_format,
    ) as xhs:  # 使用自定义参数
        download = True  # 是否下载作品文件，默认值：False
        # 返回作品详细信息，包括下载地址
        # 获取数据失败时返回空字典
        print(
            await xhs.extract(
                demo_link,
                download,
                index=[
                    1,
                    2,
                    5,
                ],
            )
        )

📋 读取剪贴板

读取剪贴板平台说明，适合 Windows 以外的用户（Mac / Linux）（点击展开）

项目使用 pyperclip 实现读取剪贴板功能，该模块在不同的系统上会有差异。

在 Windows 上，不需要额外的模块。

在 Mac 上，该模块使用 pbcopy 和 pbpaste 命令，这些命令应该随操作系统一起提供。

在 Linux 上，该模块使用 xclip 或 xsel 命令，这些命令应该随操作系统一起提供。否则，请运行 "sudo apt-get install xclip" 或 "sudo apt-get install xsel"（注意：xsel 似乎并不总是有效）

在其他 Linux 系统上，你需要安装 qtpy 或 PyQT5 模块。

⚙️ 配置文件

配置文件参数说明，适合需要直接修改程序配置参数的用户（点击展开）

项目根目录下的 ./Volume/settings.json 文件，首次运行自动生成，可以自定义程序运行参数；如果设置了无效的参数值，程序将会使用参数默认值！

如果您在程序界面修改配置时无法正常交互，可以直接编辑配置文件；如果您的计算机没有合适的程序编辑 JSON 文件，建议使用 在线工具 编辑配置文件内容，修改后需要重启软件才能生效。

参数 类型 含义 默认值
mapping_data str: str #作者别名映射表，格式：作者ID: 作者别名 无
work_path str 作品数据 / 文件保存根路径 项目根路径/Volume
folder_name str 作品文件储存文件夹名称 Download
name_format str 作品文件名称格式，字段之间使用空格分隔，支持字段：收藏数量、评论数量、分享数量、点赞数量、作品标签、作品ID、作品标题、作品描述、作品类型、发布时间、最后更新时间、作者昵称、作者ID 发布时间 作者昵称 作品标题
impersonate str 浏览器模拟目标；参考 curl_cffi 文档 chrome146
cookie str 小红书网页版 Cookie，无需登录，非必需参数！ 无
proxy str 设置程序代理 null
proxy_download bool 下载文件时，是否使用 proxy 参数的网络代理 false
timeout int 请求数据超时限制，单位：秒 10
chunk int 下载文件时，每次从服务器获取的数据块大小，单位：字节 2097152(2 MB)
max_retry int 请求数据失败时，重试的最大次数，单位：秒 5
record_data bool 是否保存作品数据至 SQLite 数据库（所有作品统一保存） false
image_format str 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
部分作品没有 HEIC 格式的文件，此时下载的文件可能为 WEBP 格式！
设置为 AUTO 时表示动态格式，实际格式取决于服务器响应数据！		 JPEG
image_download bool 图文、图集作品文件下载开关 true
video_download bool 视频作品文件下载开关 true
video_cover_download bool 视频作品封面下载开关；封面格式与图文作品文件格式一致 false
live_download bool 图文动图文件下载开关 false
video_preference str 视频作品文件下载偏好；含义：resolution：分辨率优先；bitrate：码率优先；size：文件大小优先 resolution
folder_mode bool 是否将每个作品的文件储存至单独的文件夹；文件夹名称与文件名称保持一致 false
download_record bool 是否记录下载成功的作品 ID，如果开启，程序将会自动跳过下载存在记录的作品 true
author_archive bool #是否将每个作者的作品储存至单独的文件夹；文件夹名称为 作者ID_作者昵称 false
write_mtime bool 是否将作品文件的 修改时间 属性修改为作品的发布时间 false
language str 设置程序语言，目前支持：zh_CN、en_US

XHS-Downloader (JoeanAmier/XHS-Downloader)

Searching Database…

13K ·GitHub
XHS-Downloader
What is this?XHS-Downloader is a tool for extracting share links and downloading posts (images, videos, live photos and covers) from Xiaohongshu (XiaoHongShu / RedNote).
Is this a desktop app, a CLI, or a server?It is all of those: a Python program that can run as a GUI/TUI app, a command-line tool, or as an API/MCP server, plus a companion Tampermonkey userscript that extracts links from the Xiaohongshu website.
How do I get it running?Download the prebuilt executable for Mac OS or Windows 10+, pull the Docker image (joeanamier/xhs-downloader), or run from source with `pip install -r requirements.txt` (or `uv sync`) followed by `python main.py`.
What do I need installed to run it from source?Running from source requires Python 3.12 or newer; the Mac/Windows executables need no extra dependencies, and the browser side needs the Tampermonkey userscript manager.
Does it work fine without logging in or setting a Cookie?Cookie is optional, but without one video downloads are limited to low resolution; also the 'read Cookie from browser' feature is currently broken, and Docker mode cannot use the clipboard-based command-line download mode.
Which operating systems does the prebuilt app support?Prebuilt executables are provided for Mac OS and Windows 10 and above; Linux and other platforms are supported by running from source or via Docker.
Does the Tampermonkey script download files by itself?No, the userscript only extracts links (or pushes a download task to the running program via 'scriptserver'); the actual downloading and file handling is done by the main Python program.
What image formats can it save photo posts as?The imageformat setting supports AUTO, PNG, WEBP, JPEG and HEIC, with JPEG as the default and WEBP used as a fallback when HEIC is unavailable.
Can I use this as a library in my own code?Yes, the async XHS class shown in example.py lets you configure parameters programmatically and call xhs.extract(link, download=True) to fetch or download a post for custom integrations.
Does it integrate with AI assistants?Yes, running `python main.py mcp` starts an MCP server so AI tools can call it to fetch post info or trigger downloads directly from a chat interface.
What are similar projects?TikTokDownloader, Douyin_TikTok_Download_API, autoclip, gpt4free, 3d-asset-server, catbus, Agent-Reach, FreePEP
Which topics is it in?pyinstaller, rednote, tampermonkey, userscript, xiaohongshu, image, downloader, fastapi, web-scraping, tui, json, video
Creator
JoeanAmier
Size
18.6 MB
Stars
13K
Updated
CommitSep 16Release2.8Sep 12
Age
3y
Commits · 90 Days