In today’s content-driven era, XiaoHongShu (XHS/RedNote) has become one of the primary sources of high-quality visual content—from tutorials and lifestyle tips to creative inspirations. However, users often face a common challenge: saving content is far more difficult than bookmarking it. The official app offers no download options, while third-party tools are often incomplete or leave intrusive watermarks.
Enter XHS-Downloader—a completely free and open-source Python tool built with AIOHTTP, designed for efficient downloading and management of XiaoHongShu content without watermarks.
🔑 Key Features Overview
XHS-Downloader breaks the platform’s content-saving barriers and delivers a full end-to-end solution:
1️⃣ Link Extraction Capabilities
- Account-Based: Extract links from a user’s posts, collections, likes, or albums.
- Search-Based: Grab links from search results or user profile pages.
- Batch Processing: Input multiple links at once (space-separated) with automatic filtering of invalid URLs.
2️⃣ Metadata Collection & Download
- Metadata Extraction: Title, description, author, publish date, and more.
- Watermark-Free Downloads: Unique parsing technology ensures clean media files.
- LivePhoto Support: Download dynamic photos (watermarked).
3️⃣ Smart File Management
- Duplicate Filtering: Skip already-downloaded files based on work ID.
- Integrity Check: Auto-resume interrupted downloads.
- Flexible Storage: Store files in a single folder or per-work folders.
- Custom Format: Convert image works to PNG or WEBP formats.
4️⃣ Multi-Mode Operation
- Clipboard Monitoring: Automatically detects copied XHS links and triggers downloads.
- API Server Mode: Provides HTTP API for programmatic use.
- Command-Line Control: Download specific images from a post by index.
⚙️ Configuration Parameters (settings.json)
| Parameter | Type | Description | Default |
|---|---|---|---|
| cookie | string | XHS web cookie | Empty (must be set) |
| image_format | string | Image download format | PNG |
| folder_mode | boolean | Create a folder per post | false |
| chunk | integer | Download chunk size (bytes) | 1048576 (1MB) |
| max_retry | integer | Retry attempts on failure | 5 |
| proxy | string | Proxy address | null |
📥 Installation Guide
🖱 Direct Program Execution (Beginner-Friendly)
- Download from GitHub Releases.
- Extract and run:
- Windows: Double-click
main.exe - MacOS: Run
./mainin Terminal (grant execution permission)
- Files will be saved to
./_internal/Downloadby default.
🐳 Docker Container
“`bash
docker pull joeanamier/xhs-downloader
docker run -it joeanamier/xhs-downloader
Or run in API server mode
docker run -it joeanamier/xhs-downloader python main.py server
“`
⌨ Source Code Execution (Advanced Users)
“`bash
git clone https://github.com/JoeanAmier/XHS-Downloader.git
cd XHS-Downloader
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
python main.py
“`
🚀 Usage Guide
Basic Download Steps
- Launch the program and copy an XHS link (supported formats):
“`
https://www.xiaohongshu.com/explore/63b275a30000000019020185
https://www.xiaohongshu.com/discovery/item/64edb460000000001f03cadc
https://xhslink.com/XXXXXX
“`
- Click “Read Clipboard” to auto-fill the link.
- Select “Download Watermark-Free File”.
- Find your files in the
Downloadfolder.
Pro Tips
✅ Boost Success Rate with Cookies
- Open XHS in Incognito mode.
- Press F12 → Console → type `document.cookie` → copy output.
- Paste into the `cookie` field in `settings.json`.
✅ Batch Collection with Tampermonkey
- Install Tampermonkey.
- Add the XHS-Downloader User Script.
- Browse XHS to auto-extract all visible post links.
✅ Precise CLI Downloads
“`bash
Download only image 1 and 3 of a post
python main.py –url “https://www.xiaohongshu.com/explore/xxxx” –index 1,3
“`
✅ Run as API Server
“`python
import requests
server = “http://localhost:8000/xhs/”
data = {
“url”: “https://www.xiaohongshu.com/explore/123456789”,
“download”: True,
“index”: [2, 4]
}
response = requests.post(server, json=data)
print(response.json())
“`
🔥 Why Choose XHS-Downloader?
| Feature | XHS-Downloader ✅ | IDM/FDM ❌ | Online Tools ⚠️ |
|---|---|---|---|
| Watermark-Free | ✅ Yes | ❌ No | ⚠️ Some |
| Structured Metadata | ✅ Yes | ❌ No | ❌ No |
| Batch Processing | ✅ Yes | ✅ Yes | ❌ No |
| Cross-Platform | ✅ Yes | ⚠️ Mostly Windows | ✅ Yes |
| Clipboard Monitoring | ✅ Yes | ❌ No | ❌ No |
| Open-Source | ✅ Yes | ❌ No | ❌ No |
| Tampermonkey Support | ✅ Yes | ❌ No | ❌ No |
⚠️ Tips & Troubleshooting
- Slow downloads? Increase `chunk` size (e.g., 10MB) and enable proxy.
- Empty results? Refresh your Cookie (valid for ~24h).
- Mac issues? Run `chmod +x main` to grant permissions.
📝 Ethical Use
XHS-Downloader follows a neutral, educational purpose principle.
🚫 No Commercial Use – Personal learning/research only.
⚖️ Respect Copyright – Always credit authors when sharing.
🔒 Privacy Protection – Do not download private/non-public content.
💡 The latest version supports resume downloads and LivePhoto merging. Developers can try the cutting-edge features by compiling from source, while regular users can get stable builds from GitHub Releases.
In a dark-green Windows Terminal, lines of white logs flash across the screen. When “Download completed!” finally appears, the once online-only XiaoHongShu posts now lie quietly in your local folder—no watermarks, no platform restrictions, just pure, preserved content.