Xiaohongshu Anti-Crawling#

Xiaohongshu (小红书) enforces several overlapping access control layers that cause extraction failures in XHS-Downloader:

1. xsec_token requirement — notes and images cannot be fetched without a valid, server-issued security token in the URL.
2. Geographic IP restrictions — the platform blocks non-mainland-China IPs, including VPNs and proxies.
3. Rate limiting / CAPTCHA — excessive request frequency triggers temporary bans or CAPTCHA challenges.
4. URL domain changes — share links migrated from .com to .cn in July 2026, breaking hardcoded regex patterns.

The project maintainer treats these as platform-level risk controls and does not attempt to circumvent them 1. For users affected by geographic or token restrictions, the Tampermonkey browser userscript is the primary recommended alternative 2.

xsec_token Requirement#

xsec_token is a server-generated security token Xiaohongshu requires as a URL query parameter to access note and image content 1. URLs without it (e.g., https://www.xiaohongshu.com/explore/<note_id>) now fail to retrieve content; the correct format is:

https://www.xiaohongshu.com/explore/<note_id>?xsec_token=<token>

Key properties 3:

• The token is tied to the requesting account, date, and source — it is not a fixed value.
• It cannot be derived from a note_id alone.
• Tokens obtained at collection time must be reused at download time; swapping tokens causes failures 4.

In the codebase, the token is not parsed separately — it is passed through as part of the full URL string to request_url() without decomposition.

How to Obtain xsec_token#

Geographic IP Restrictions#

Xiaohongshu enforces mainland China ISP IP requirements at the platform level. Users outside China — including those using VPNs or proxies — encounter CAPTCHA and "failed to retrieve data" errors regardless of whether they provide a valid cookie 5 2.

This is a server-side enforcement mechanism, not a bug in XHS-Downloader. The tool has no built-in proxy or geo-bypass capability.

If you can browse the works normally in the browser, you can consider using the Tampermonkey user script. — maintainer 2

Rate Limiting and CAPTCHA#

Rapid sequential requests trigger Xiaohongshu's risk control, resulting in temporary bans (typically ~24 hours) or CAPTCHA challenges 2. Bans can persist even for normal browser sessions if the account was flagged via API access 2.

XHS-Downloader mitigates this with a randomized inter-request delay using a lognormal distribution — averaging 6 seconds with a 0.5-second floor — called after every successful HTTP response 6:

# source/module/tools.py
def get_wait_time(avg_delay=6.0, sigma=0.6) -> float:
    mu = log(avg_delay) - (sigma**2 / 2)
    return max(0.5, lognormvariate(mu, sigma))

Users running from source code can tune avg_delay and sigma directly. The compiled executable does not support this change 2.

HTTP errors (including rate-limit responses) are caught at request_url() and logged, returning an empty string for upstream handling.

Domain Change: .com → .cn (July 2026)#

In July 2026, Xiaohongshu began issuing share links with a .cn domain suffix instead of .com 7. XHS-Downloader's URL matching patterns in source/application/app.py are hardcoded to .com only:

LINK_XHS = compile(r"(?:https?://)?www\.xiaohongshu\.com/explore/\S+")
SHARE_XHS = compile(r"(?:https?://)?www\.xiaohongshu\.com/discovery/item/\S+")
SHORT = compile(r"(?:https?://)?xhslink\.com/[^\s\"<>\\^`{|}，。；！？、【】《》]+")

When the app's extract_links() method encounters a .cn URL, it silently discards it, producing a "提取小红书作品链接失败" (failed to extract link) warning with no content retrieved 7.

Fix: Update the patterns to (?:com|cn) 7. The maintainer has directed users to use the develop branch while this is resolved 8.

Users can manually work around this by replacing .cn with .com in the shared URL before inputting it. 7

Workarounds and Mitigations#

Cookie Configuration#

A valid browser cookie improves access (required for higher video quality and some content) but does not bypass geographic IP restrictions 9. See the Video Quality Selection article for cookie setup steps.