XHS-Downloader

简体中文 | English

🔥 RedNote Link Extraction/Content Collection Tool：Extract account-published, favorites, and liked notes links; extract search result notes links and user links; collect RedNote notes information; extract RedNote notes download addresses; download RedNote notes files!

🔥 "RedNote", "XiaoHongShu" and "小红书" have the same meaning, and this project is collectively referred to as "RedNote".

⭐ Due to the author's limited energy, I was unable to update the English document in a timely manner, and the content may have become outdated, partial translation is machine translation, the translation result may be incorrect, Suggest referring to Chinese documentation. If you want to contribute to translation, we warmly welcome you.

📑 Project Features

Program Features and User Script Features (Click to Expand)

Program Features
• ✅ Collect RedNote notes information
• ✅ Extract RedNote notes download addresses
• ✅ Download RedNote notes files
• ✅ Download RedNote livePhoto files
• ✅ Automatically skip already downloaded notes files
• ✅ notes file integrity handling mechanism
• ✅ Customizable image notes file download format
• ✅ Persistently store notes information to files
• ✅ Store notes files to a separate folder
• ✅ Background clipboard monitoring for notes download
• ✅ Record downloaded notes IDs
• ✅ Support command line for downloading notes files
• ☑️ Read cookies from browser
• ✅ Customizable file name format
• ✅ Support API call functionality
• ✅ Support MCP call functionality
• ✅ Support file breakpoint resume download
• ✅ Intelligent recognition of notes file types
• ✅ Supports author alias configuration
• ✅ Automatic author nickname updates

Script Features
• ✅ Download RedNote notes files
• ✅ Extract discovery page notes links
• ✅ Extract account-published notes links
• ✅ Extract account-favorited notes links
• ✅ Extract account-liked notes links
• ✅ Extract account-board notes links
• ✅ Extract search result notes links
• ✅ Extract search result user links

📸 Program Screenshots

Watch Demo on Bilibili；Watch Demo on YouTube

---

---

🔗 Supported Links

• https://www.xiaohongshu.com/explore/NoteID?xsec_token=XXX
• https://www.xiaohongshu.com/discovery/item/NoteID?xsec_token=XXX
• https://www.xiaohongshu.com/user/profile/AuthorID/NoteID?xsec_token=XXX
• https://xhslink.com/ShareCode
Supports entering multiple notes links at once, separated by spaces; the program will automatically extract valid links without additional processing!

🪟 About the Terminal

⭐ It is recommended to use the Windows Terminal (default terminal for Windows 11) to run the program for the best display effect!

🥣 Usage

If you only need to download notes files, it is recommended to choose Program Run; if you have other needs, it is recommended to choose Source Code Run!

⚠️ When Cookie is not set, video works can only be downloaded in low resolution; it is recommended to configure Cookie to obtain higher quality (no need to log in to the account)!

🖱 Program Run

⭐ Mac OS, Windows 10 and above users can go to Releases or Actions to download the program package, unzip it, open the program folder, and double-click to run main to use.

⭐ This project includes GitHub Actions for automatic building executable files. Users can use GitHub Actions to build the latest source code into executable files at any time!

⭐ For the automatic building executable files tutorial, please refer to the Build of Executable File Guide section of this document. If you need a more detailed step-by-step tutorial with illustrations, please check out this article!

Note: Due to the macOS platform's executable file main not being code-signed, it will be restricted by system security measures on first run. Please execute the command xattr -cr project_folder_path in the terminal to remove the security flag, after which it can run normally.

If you use the program in this way, the default download path for files is: ._internal\Volume\Download; the configuration file path is: ._internal\Volume\settings.json

Update Methods

Method 1: Download and extract the files, then copy the old version of the _internal\Volume folder into the new version's _internal folder.

Method 2: Download and extract the files (do not run the program), then copy all files and directly overwrite the old version.

⌨️ Run from Source Code

1. Install Python interpreter version ≥3.12
2. Download the latest source code or the source code released in Releases to your local machine
Install project dependencies using pip
1. Run the command python -m venv venv to create a virtual environment (optional)
2. Run the command .\venv\Scripts\activate.ps1 or venv\Scripts\activate to activate the virtual environment (optional)
3. Run the command pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt to install the required modules for the program
4. Run the command python .\main.py or python main.py to start XHS-Downloader
Install project dependencies using uv (recommended)
1. Run the command uv sync --no-dev to synchronize environment dependencies
2. Run the command uv run main.py to start XHS-Downloader

⌨️ Docker Run

1. Get Image
• Method 1: Build the image using the Dockerfile
• Method 2: Pull the image using the command docker pull joeanamier/xhs-downloader
• Method 3: Pull the image using the command docker pull ghcr.io/joeanamier/xhs-downloader
2. Create Container
• TUI Mode: docker run --name ContainerName(optional) -p HostPort:5556 -v xhs_downloader_volume:/app/Volume -it <image name>
• API Mode: docker run --name ContainerName(optional) -p HostPort:5556 -v xhs_downloader_volume:/app/Volume -it <image name> python main.py api
• MCP Mode: docker run --name ContainerName(optional) -p HostPort:5556 -v xhs_downloader_volume:/app/Volume -it <image name> python main.py mcp
Note: The <image name> here must be consistent with the image name you used in the first step (joeanamier/xhs-downloader or ghcr.io/joeanamier/xhs-downloader)
3. Run Container
   • Start Container: docker start -i ContainerName/ContainerID
   • Restart Container: docker restart -i ContainerName/ContainerID

When running the project via Docker, the command line call mode is not supported. The clipboard reading and clipboard monitoring functions are unavailable, but pasting content notes fine. Please provide feedback if other features are not functioning properly!

🛠 Command Line Mode

The project supports command line mode. If you want to download specific images from a text and image notes, you can use this mode to set the image sequence number you want to download!

Note: When the --index parameter is not set, multiple notes links can be passed in. All links must be enclosed in quotation marks and separated by spaces. When the --index parameter is set, multiple notes links are not supported. Even if multiple links are passed in, the program will only process the first link!

The bool type parameters support setting with true, false, 1, 0, yes, no, on or off (case insensitive).

Read Browser Cookies

This feature is no longer available. Please refer to the Obtain Cookie tutorial!

You can use the command line to read cookies from browser and write them to the configuration file!

Command example: python .\main.py --browser_cookie Chrome --update_settings

Compatibility note: The third-party module this feature depends on has not been updated for a long time and may not properly support the latest browser versions. If the feature is not working properly, please try obtaining cookies manually!

---

---

🖥 Server Mode

Server modes include API mode and MCP mode!

API Mode

Start: Run the command: python .\main.py api

Stop: Press Ctrl + C to stop the server

Open http://127.0.0.1:5556/docs or http://127.0.0.1:5556/redoc; you will see automatically generated interactive API documentation!

Request endpoint: /xhs/detail

Request method: POST

Request format: JSON

Request parameters:

Parameter	Type	Description	Default
url	str	RedNote notes link, auto-extraction, does not support multiple links; Required parameter	None
download	bool	Whether to download the notes file; set to true will take more time; Optional parameter	false
index	list[int]	Download specific image files by index, only effective for text and image notes; not effective when the download parameter is set to false; Optional parameter	null
cookie	str	Cookie used when requesting data; Optional parameter	Settings cookie Value
proxy	str	Proxy used when requesting data; Optional parameter	Settings proxy Value
skip	bool	Whether to skip notes with download records; set to true will not return notes data with download records; Optional parameter	false

Code example:

async def example_api():
    """通过 API 设置参数，适合二次开发"""
    server = "http://127.0.0.1:5556/xhs/detail"
    data = {
        "url": "",  # 必需参数
        "download": True,
        "index": [
            3,
            6,
            9,