🔥 RedNote Link Extraction/Content Collection Tool：Extract account-published, favorites, and liked works links; extract search result works links and user links; collect RedNote works information; extract RedNote works download addresses; download RedNote watermark-free works 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 works information
- ✅ Extract RedNote works download addresses
- ✅ Download RedNote watermark-free works files
- ✅ Download RedNote livePhoto files (watermark)
- ✅ Automatically skip already downloaded works files
- ✅ works file integrity handling mechanism
- ✅ Customizable image works file download format
- ✅ Persistently store works information to files
- ✅ Store works files to a separate folder
- ✅ Background clipboard monitoring for works download
- ✅ Record downloaded works IDs
- ✅ Support command line for downloading works 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 works file types
- ✅ Supports author alias configuration
- ✅ Automatic author nickname updates
- Script Features
- ✅ Download RedNote watermark-free works files
- ✅ Extract discovery page works links
- ✅ Extract account-published works links
- ✅ Extract account-favorited works links
- ✅ Extract account-liked works links
- ✅ Extract account-board works links
- ✅ Extract search result works links
- ✅ Extract search result user links
📸 Program Screenshots
Watch Demo on Bilibili；Watch Demo on YouTube
🔗 Supported Links
https://www.xiaohongshu.com/explore/WorksID?xsec_token=XXXhttps://www.xiaohongshu.com/discovery/item/WorksID?xsec_token=XXXhttps://www.xiaohongshu.com/user/profile/AuthorID/WorksID?xsec_token=XXXhttps://xhslink.com/ShareCode
Supports entering multiple works 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 watermark-free works files, it is recommended to choose Program Run; if you have other needs, it is recommended to choose Source Code Run!
Starting from version 2.2, if there are no abnormalities in project functionality, there is no need to handle cookies separately!
🖱 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
- Install Python interpreter version
3.12 - Download the latest source code or the source code released in Releases to your local machine
- Run the command
python -m venv venvto create a virtual environment (optional) - Run the command
.\venv\Scripts\activate.ps1orvenv\Scripts\activateto activate the virtual environment (optional) - Run the command
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txtto install the required modules for the program - Run the command
python .\main.pyorpython main.pyto start XHS-Downloader - Run the command
uv venvto create a virtual environment - Run the command
uv syncto synchronize environment dependencies - Run the command
uv run main.pyto start XHS-Downloader
- Install project dependencies using pip
- Install project dependencies using uv (recommended)
⌨️ Docker Run
- 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 - 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 - Run Container
- Start Container:
docker start -i ContainerName/ContainerID - Restart Container:
docker restart -i ContainerName/ContainerID
- Start Container:
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)
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 works 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 works, you can use this mode to set the image sequence number you want to download!
Note: When the --index parameter is not set, multiple works links can be passed in. All links must be enclosed in quotation marks and separated by spaces. When the --index parameter is set, multiple works 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
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 works link, auto-extraction, does not support multiple links; Required parameter | None |
| download | bool | Whether to download the works 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 works; 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 works with download records; set to true will not return works 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,
],
"proxy": "http://127.0.0.1:10808",
}
response = post(server, json=data, timeout=10)
print(response.json())
MCP Mode
Start: Run the command: python .\main.py mcp
Stop: Press Ctrl + C to stop the server
MCP Configuration Example
Streamable HTTP
MCP URL:http://127.0.0.1:5556/mcp/
MCP Invocation Example
MCP Function and Call Example (Click to Expand)
Retrieve RedNote Works Information
Download RedNote Works Files
When downloading images, you can specify the sequence numbers of the images to download. By default, post information is not returned. If you need the post information, please explicitly state so during the conversation.
📜 Others
- Due to the date information carried in the links of RedNote works, using links obtained from previous dates may be subject to risk control. It is recommended to use the latest RedNote works links when downloading RedNote work files
- Windows system requires running programs as an administrator to read Chromium, Chrome, Edge browser cookies
- If the function to save works data to a file is enabled, the works data will be stored by default in the
./Volume/Download/ExploreData.dbfile - The program's download records will be stored in the
./Volume/ExploreID.dbfile - To prevent high-frequency requests from impacting the platform's servers, this project includes a built-in request delay mechanism
🕹 User Script
If your browser has the Tampermonkey extension installed, you can use the userscript to try the project's features!
Userscript links (right-click to copy the link): master branch, develop branch
View Tampermonkey userscript screenshots (click to expand)
Note: Using the XHS-Downloader user script to batch extract works links, in combination with the XHS-Downloader program, can achieve batch downloading of watermark-free works files!
📜 Script Instructions
- When downloading watermark-free works from Xiaohongshu, the script requires time to process the files. Please wait for a moment and do not click the download button multiple times.
- Watermark-free image files are in PNG format; watermark-free video files are larger and may take longer to process. Page redirects may cause download failures.
- When extracting links for posts, collects, likes, and board from an account, the script can automatically scroll the page until all works are loaded.
- When extracting recommended works links, search works, and user links, the script can automatically scroll a specified number of times to load more content. The default number of page scrolls is 50.
- The automatic scrolling page function is turned off by default; Users can freely open and modify the number of times the page is scrolled, and the modification will take effect immediately.
- If the automatic page scroll feature is not enabled, users need to manually scroll the page to load more content before performing other actions.
- Support packaging and downloading of work files; This feature is enabled by default, and works from multiple files will be downloaded in compressed file format
- Using global proxy tools may cause script download failures. If there are issues, please try disabling the proxy tool. If necessary, contact the author for feedback.
- XHS-Downloader userscript only implements the data collection functionality for visible content and does not include any paid or cracked features.
The automatic page scroll feature has been refactored and is turned off by default! Enabling this feature may be detected as automated behavior by Xiaohongshu, potentially resulting in account risk control or banning.
💻 Secondary Development
If you have other needs, you can perform code calls or modifications based on the comments in 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 = "作品标题 作品描述"
user_agent = "" # User-Agent
cookie = "" # 小红书网页版 Cookie，无需登录，可选参数，登录状态对数据采集有影响
proxy = None # 网络代理
timeout = 5 # 请求数据超时限制，单位：秒，默认值：10
chunk = 1024 * 1024 * 10 # 下载文件时，每次从服务器获取的数据块大小，单位：字节
max_retry = 2 # 请求数据失败时，重试的最大次数，单位：秒，默认值：5
record_data = False # 是否保存作品数据至文件
image_format = "WEBP" # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
folder_mode = False # 是否将每个作品的文件储存至单独的文件夹
image_download = True # 图文、图集作品文件下载开关
video_download = True # 视频作品文件下载开关
live_download = False # 图文动图文件下载开关
download_record = True # 是否记录下载成功的作品 ID
language = "zh_CN" # 设置程序提示语言
author_archive = True # 是否将每个作者的作品存至单独的文件夹
write_mtime = True # 是否将作品文件的 修改时间 修改为作品的发布时间
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,
user_agent=user_agent,
cookie=cookie,
proxy=proxy,
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,
live_download=live_download,
download_record=download_record,
language=language,
read_cookie=read_cookie,
author_archive=author_archive,
write_mtime=write_mtime,
) as xhs: # 使用自定义参数
download = True # 是否下载作品文件，默认值：False
# 返回作品详细信息，包括下载地址
# 获取数据失败时返回空字典
print(
await xhs.extract(
demo_link,
download,
index=[
1,
2,
5,
],
)
)
📋 Read Clipboard
The project uses pyperclip to implement clipboard reading functionality, which varies across different systems.
On Windows, no additional modules are needed.
On Mac, this module makes use of the pbcopy and pbpaste commands, which should come with the os.
On Linux, this module makes use of the xclip or xsel commands, which should come with the os. Otherwise run "sudo apt-get install xclip" or "sudo apt-get install xsel" (Note: xsel does not always seem to work.)
Otherwise on Linux, you will need the qtpy or PyQT5 modules installed.
⚙️ Configuration File
The ./Volume/settings.json file in the project's root directory is automatically generated on the first run. You can use it to customize the program's operating parameters. If an invalid parameter value is set, the program will revert to its default value.
If you are unable to modify settings through the program's interface, you can edit this configuration file directly. If your computer lacks a suitable program for editing JSON files, we recommend using an online tool. Remember to restart the software after making changes for them to take effect.
| Parameter | Type | Description | Default Value |
|---|---|---|---|
| mapping_data | str: str | #Author alias mapping data, format: author ID: author alias |
null |
| work_path | str | Root path for saving works data/files | Project root path/Volume |
| folder_name | str | Name of the folder for storing works files | Download |
| name_format | str | #Format of works file name, separated by spaces between fields, supports fields: 收藏数量、评论数量、分享数量、点赞数量、作品标签、作品ID、作品标题、作品描述、作品类型、发布时间、最后更新时间、作者昵称、作者ID |
发布时间 作者昵称 作品标题 |
| user_agent | str | Browser User Agent | Built-in Chrome User Agent |
| cookie | str | RedNote web version cookie, No login required, non essential parameters! | None |
| proxy | str | Set program proxy | null |
| timeout | int | Request data timeout limit, in seconds | 10 |
| chunk | int | Size of data chunk to fetch from the server each time when downloading files, in bytes | 2097152(2 MB) |
| max_retry | int | Maximum number of retries when requesting data fails | 5 |
| record_data | bool | Whether to save works data to a file, saved in SQLite format |
false |
| image_format | str | Download format for image works files, supported: AUTO、PNG、WEBP、JPEG、HEICSome works do not have files in HEIC format, and the downloaded files may be in WEBP format When set to AUTO, it represents dynamic format, and the actual format depends on the server's response data |
PNG |
| image_download | bool | Switch for downloading image and atlas works files | true |
| video_download | bool | Switch for downloading video works files | true |
| live_download | bool | Switch for downloading animated image files | false |
| folder_mode | bool | Whether to store each works files in a separate folder; the folder name matches the file name | false |
| download_record | bool | Do record the ID of successfully downloaded works? If enabled, the program will automatically skip downloading works with records | true |
| author_archive | bool | #Whether to save each author's works into a separate folder; The folder name is authorID_nickname |
false |
| write_mtime | bool | Whether to modify the modified time attribute of the works file to the publication time of the works. |
false |
| language | str | Set program language. Currently supported: zh_CN, en_US |
zh_CN |
name_format instructions (Currently only supports Chinese values) :
收藏数量: Number of Collections评论数量: Number of Comments分享数量: Number of Shares点赞数量: Number of Likes作品标签: Works Tags作品ID: Works ID作品标题: Works Title作品描述: Works Description作品类型: Works Type发布时间: Publish Time最后更新时间: Last Updated Time作者昵称: Author Nickname作者ID: Author ID
Additional Notes: The parameters user_agent examples are provided for reference; Strongly recommend setting according to actual browser information!
🌐 Cookie
Starting from version 2.2, if there are no abnormalities in project functionality, there is no need to handle cookies separately!
- Open the browser (optional: start in incognito mode) and visit
https://www.xiaohongshu.com/explore - Log in to your RedNote account (can be skipped)
- Press
F12to open the developer tools - Select the
Networktab - Check
Preserve log - In the
Filterinput box, entercookie-name:web_session - Select the
Fetch/XHRfilter - Click on any piece of works on the RedNote page
- In the
Networktab, select any data packet (if no packets appear, repeat step 7) - Copy and paste the entire Cookie into the program or configuration file
🗳 Download Records
XHS-Downloader will store the IDs of downloaded works in a database. When downloading the same works again, XHS-Downloader will automatically skip the file download (even if the works file does not exist). If you want to re-download the works file, please delete the corresponding works ID from the database and then use XHS-Downloader to download the works file again!
This feature is enabled by default. If it is turned off, XHS-Downloader will check if the file exists. If the file exists, it will skip the download!
Build of Executable File Guide
Build of Executable File Guide (Click to Expand)
This guide will walk you through forking this repository and executing GitHub Actions to automatically build and package the program based on the latest source code!
Steps to Use
1. Fork the Repository
- Click the Fork button at the top right of the project repository to fork it to your personal GitHub account
- Your forked repository address will look like this:
https://github.com/your-username/this-repo
2. Enable GitHub Actions
- Go to the page of your forked repository
- Click the Settings tab at the top
- Click the Actions tab on the right
- Click the General option
- Under Actions permissions, select Allow all actions and reusable workflows and click the Save button
3. Manually Trigger the Build Process
- In your forked repository, click the Actions tab at the top
- Find the workflow named 构建可执行文件
- Click the Run workflow button on the right:
- Select the master or develop branch
- Click Run workflow
4. Check the Build Progress
- On the Actions page, you can see the execution records of the triggered workflow
- Click on the run record to view detailed logs to check the build progress and status
5. Download the Build Result
- Once the build is complete, go to the corresponding run record page
- In the Artifacts section at the bottom of the page, you will see the built result file
- Click to download and save it to your local machine to get the built program
Notes
-
Resource Usage:
- GitHub provides free build environments for Actions, with a monthly usage limit (2000 minutes) for free-tier users
-
Code Modifications:
- You are free to modify the code in your forked repository to customize the build process
- After making changes, you can trigger the build process again to get your customized version
-
Stay in Sync with the Main Repository:
- If the main repository is updated with new code or workflows, it is recommended that you periodically sync your forked repository to get the latest features and fixes
Frequently Asked Questions
Q1: Why can't I trigger the workflow?
A: Please ensure that you have followed the steps to Enable Actions. Otherwise, GitHub will prevent the workflow from running
Q2: What should I do if the build process fails?
A:
- Check the run logs to understand the cause of the failure
- Ensure there are no syntax errors or dependency issues in the code
- If the problem persists, please open an issue on the Issues page
Q3: Can I directly use the Actions from the main repository?
A: Due to permission restrictions, you cannot directly trigger Actions from the main repository. Please use the forked repository to execute the build process
⭐ Star History
♥️ Support the Project
If XHS-Downloader has been helpful to you, please consider giving it a Star ⭐. Thank you for your support!
| 微信(WeChat) | 支付宝(Alipay) |
|---|---|
 |
 |
If you are willing, you may consider making a donation to provide additional support for XHS-Downloader!
🌟 Contribution Guidelines
Welcome to contributing to this project! To keep the codebase clean, efficient, and easy to maintain, please read the following guidelines carefully to ensure that your contributions can be accepted and integrated smoothly.
- Before starting development, please pull the latest code from the
developbranch as the basis for your modifications; this helps avoid merge conflicts and ensures your changes are based on the latest state of the project. - If your changes involve multiple unrelated features or issues, please split them into several independent commits or pull requests.
- Each pull request should focus on a single feature or fix as much as possible, to facilitate code review and testing.
- Follow the existing coding style; make sure your code is consistent with the style already present in the project; please use the Ruff tool to maintain code formatting standards.
- Write code that is easy to read; add appropriate annotation to help others understand your intentions.
- Each commit should include a clear and concise commit message describing the changes made. The commit message should follow this format:
<type>: <short description> - When you are ready to submit a pull request, please prioritize submitting them to the
developbranch; this provides maintainers with a buffer zone for additional testing and review before final merging into themasterbranch. - It is recommended to communicate with the author before starting development or when encountering questions to ensure alignment in direction and avoid redundant efforts or unnecessary commits.
Reference materials:
✉️ Contact the Author
- Author's Email：yonglelolu@foxmail.com
- Author's WeChat: Downloader_Tools
- Discord Community: Click to Join the Community
✨ Other Open Source Projects by the Author:
- DouK-Downloader（抖音、TikTok）：https://github.com/JoeanAmier/TikTokDownloader
- KS-Downloader（快手、KuaiShou）：https://github.com/JoeanAmier/KS-Downloader
💰 Project Sponsorship
DartNode
ZMTO
ZMTO: A professional cloud infrastructure provider offering sophisticated solutions with reliable technology and expert support. We also empower qualified open source initiatives with enterprise-grade VPS infrastructure, driving sustainable development and innovation in the open source ecosystem.
⚠️ Disclaimer
- The user's use of this project is entirely at their own discretion and responsibility. The author assumes no liability for any losses, claims, or risks arising from the user's use of this project.
- The code and functionalities provided by the author of this project are based on current knowledge and technological developments. The author strives to ensure the correctness and security of the code according to existing technical capabilities but does not guarantee that the code is entirely free of errors or defects.
- All third-party libraries, plugins, or services relied upon by this project follow their respective open-source or commercial licenses. Users must review and comply with those license agreements. The author assumes no responsibility for the stability, security, or compliance of third-party components.
- Users must strictly comply with the requirements of the GNU General Public License v3.0 when using this project and properly indicate that the code was used under the GNU General Public License v3.0.
- When using the code and features of this project, users must independently research relevant laws and regulations and ensure their actions are legal and compliant. Any legal liabilities or risks arising from violations of laws and regulations shall be borne solely by the user.
- Users must not use this tool to engage in any activities that infringe intellectual property rights, including but not limited to downloading or distributing copyright-protected content without authorization. The developers do not participate in, support, or endorse any unauthorized acquisition or distribution of illegal content.
- This project assumes no responsibility for the compliance of any data processing activities (including collection, storage, and transmission) conducted by users. Users must comply with relevant laws and regulations and ensure that their processing activities are lawful and proper. Legal liabilities resulting from non-compliant operations shall be borne by the user.
- Under no circumstances may users associate the author, contributors, or other related parties of this project with their usage of the project, nor may they hold these parties responsible for any loss or damage arising from such usage.
- The author of this project will not provide a paid version of the XHS-Downloader project, nor will they offer any commercial services related to the XHS-Downloader project.
- Any secondary development, modification, or compilation based on this project is unrelated to the original author. The original author assumes no liability for any consequences resulting from such secondary development. Users bear full responsibility for all outcomes arising from such modifications.
- This project grants no patent licenses; if the use of this project leads to patent disputes or infringement, the user bears all associated risks and responsibilities. Without written authorization from the author or rights holder, users may not use this project for any commercial promotion, marketing, or re-licensing.
- The author reserves the right to terminate service to any user who violates this disclaimer at any time and may require them to destroy all obtained code and derivative works.
- The author reserves the right to update this disclaimer at any time without prior notice. Continued use of the project constitutes acceptance of the revised terms.
💡 Project References
- https://github.com/encode/httpx/
- https://github.com/tiangolo/fastapi
- https://github.com/textualize/textual/
- https://github.com/jlowin/fastmcp
- https://github.com/omnilib/aiosqlite
- https://github.com/thewh1teagle/rookie
- https://github.com/carpedm20/emoji/
- https://github.com/asweigart/pyperclip
- https://github.com/lxml/lxml
- https://github.com/yaml/pyyaml
- https://github.com/pallets/click/
- https://github.com/encode/uvicorn
- https://github.com/Tinche/aiofiles