🔽XHS-Downloader: Unlock Watermark-Free XiaoHongShu Content

Discover XHS-Downloader, a free open-source Python tool for batch downloading watermark-free XiaoHongShu images, videos, and LivePhotos with full metadata extraction.

Complete Guide to XHS-Downloader

I. Comprehensive Feature Overview

XHS-Downloader breaks through XiaoHongShu's content access barriers, delivering an end-to-end solution:

Work Link Extraction Capabilities

• Account Dimension: Extracts links to user-published, bookmarked, liked, and album works
• Search Dimension: Captures work links and user profile links from search results
• Batch Processing: Accepts multiple links in a single input (space-separated) with automatic filtering of invalid content

Work Information Collection & Download

• Metadata Collection: Obtains structured data including work title, description, author, and publish time
• Watermark-Free Download: Exclusive parsing technology retrieves clean image/video files
• LivePhoto Support: Downloads additional dynamic photo resources (non-watermark-free)

Intelligent File Management

• Duplicate Filtering: Automatically skips downloaded files via work ID database
• Integrity Verification: Auto-resumes interrupted downloads to ensure file completeness
• Flexible Storage: Optional unified folder or per-work independent folder storage
• Custom Formats: Image works support PNG/WEBP format conversion

Multi-Mode Operation

• Clipboard Monitoring: Background real-time detection of copied XiaoHongShu links to trigger automatic downloads
• API Server Mode: Cross-program collaboration via HTTP interface calls
• Command-Line Control: Precise download of specific index images from image works

Table: Key Configuration Parameters (settings.json) 📜

II. Installation Guide: Three Methods Covering All Platforms

🖱 Direct Program Execution (Recommended for Beginners)

• Visit GitHub Releases to download the archive for your operating system

• After extracting, enter the folder:

  • Windows: Double-click main.exe
  • Mac OS: Execute ./main in terminal (requires execution permission)
• Default save path: ./_internal/Download

🐳 Docker Container Execution

# Pull image
docker pull joeanamier/xhs-downloader
# Launch TUI interface
docker run -it joeanamier/xhs-downloader
# Or enable API server mode
docker run -it joeanamier/xhs-downloader python main.py server

⌨ Source Code Execution (Developers/Advanced Users)

# Requires Python >= 3.12
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

III. Practical Usage Tutorial

Basic Download Operation

After launching the program, copy a XiaoHongShu work link (three formats supported):

• 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 Work File", and check the result in the Download folder.

Advanced Techniques

1. Cookie Setup for Better Success Rate:

   • Access https://www.xiaohongshu.com in browser incognito mode
   • Press F12 to open Developer Tools → Console tab
   • Enter document.cookie and press Enter → Copy the output
   • Paste into the cookie field in the config file

2. Tampermonkey Script for Batch Collection:

   • Install the Tampermonkey extension
   • Add the XHS-Downloader user script
   • Automatically extracts all work links while browsing XiaoHongShu
   • Combined with main program for batch downloads

3. Command-Line Precise Download:

   # Only download the 1st and 3rd images of an image work
   python main.py --url "https://www.xiaohongshu.com/explore/xxxx" --index 1,3
   # Import Cookie from Chrome
   python main.py --browser_cookie Chrome --update_settings true

4. API Server Mode:

   import requests
   server = "http://localhost:8000/xhs/"
   data = {
    "url": "https://www.xiaohongshu.com/explore/123456789",
    "download": True,
    "index": [2, 4]  # Download the 2nd and 4th images
   }
   response = requests.post(server, json=data)
   print(response.json())

IV. Comparison: Why XHS-Downloader Stands Out

Table: XiaoHongShu Download Tools Capability Matrix 🛠️

Compared to generic tools like IDM (basic download acceleration only) or EagleGet (video capture focused), XHS-Downloader's core advantages are:

• Deep Platform Adaptation: Purpose-built parsing for XiaoHongShu data structures, breaking watermark technical barriers
• Lightweight & Ad-Free: Minimal ~28MB footprint, free from commercial tool pop-ups
• Full-Chain Automation: From link discovery → metadata extraction → file download in one flow
• Privacy & Security: Open-source code eliminates backdoors; local execution avoids content upload risks

V. Advanced Tips & Troubleshooting Guide

Download Acceleration Methods

When facing slow large video downloads:

• Modify the chunk value in settings.json (recommended increase to 10MB)
• Enable proxy (proxy parameter) to bypass network throttling

• Combine with multi-threaded downloaders like Axel for direct links:

  axel -n 10 "direct video link"

Troubleshooting

• Download Interrupted: Check max_retry value (recommend >=3), enable proxy to avoid IP blocking
• Returns Empty Data: Update Cookie (validity typically 24 hours), verify link format is correct
• Mac Execution Failure: Run chmod +x main in terminal to grant execution permission

Batch Download Strategy

• Use the user script to collect all work page links from an account
• Save links to urls.txt, one per line

• Execute batch download:

  python main.py -f urls.txt

VI. Conclusion: Ethical Boundaries of Content Preservation

XHS-Downloader follows the principle of technological neutrality, providing a legitimate tool for personal learning and research. Key reminders:

• ✋ No Commercial Use: Downloaded content is limited to personal use; commercial monetization is prohibited
• ⚖️ Respect Copyright: Retain work metadata; clearly credit source and author when reposting
• 🔒 Privacy Protection: Do not download non-public content; do not breach user privacy data

The project continues to evolve, with the latest version supporting file resume/continuation and LivePhoto synthesis features. Developers are encouraged to compile from source for cutting-edge features, while general users can follow the Releases page for stable updates.

Within the Windows Terminal environment, white log lines flash across the dark green command-line interface. When the "Download completed!" prompt appears, those XiaoHongShu works that could once only be watched online now rest quietly in the local folder—no watermarks, no platform restrictions, only pure content preservation.