# xhscrawl: Python and JavaScript access to Xiaohongshu web APIs

> xhscrawl reverse-engineers Xiaohongshu web request signing so Python applications can call protected endpoints. It targets researchers and developers, but its undocumented dependencies, authorization boundaries, and limited setup guidance require careful review.

**submato/xhscrawl** — 小红书数据,xhs数据采集,小红书逆向,小红书 xs逆向,小红书爬虫,小红书数据

- Repository: https://github.com/submato/xhscrawl
- Stars: 1,504 · Forks: 186
- Language: Unknown
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/submato-xhscrawl

## Why xhscrawl targets Xiaohongshu request signing

xhscrawl addresses a specific obstacle in Xiaohongshu web automation: the web APIs use encrypted requests, and the README identifies `x-s` as the main signing element. This puts the project in the reverse-engineering category rather than ordinary API integration. A client needs more than an endpoint URL and a cookie because Xiaohongshu expects request material that the web application computes before sending a request.

The intended users appear to be Python developers and reverse engineers studying Xiaohongshu's browser-side request flow. The `demo/xhs.py` file is meant to be edited directly: the README says to replace the desired parameters and cookie, then run it. That workflow suits a controlled investigation into a particular endpoint. It does not resemble a packaged crawler with a documented command-line interface, configuration schema, or supported deployment model.

The repository also points to separate documents for individual operations such as note search, note details, comments, user search, publishing, messaging, and account-related actions. This breadth creates an adoption question that the opening description does not answer. A signer implementation can be useful for research, while action endpoints may require an authenticated account and can change the state of that account. The correct scope should therefore be established before treating the project as a general Xiaohongshu data client.

## Python, JavaScript, and Node.js in the request path

The repository layout and runtime requirements indicate a mixed-language design. Python appears to orchestrate requests, while JavaScript performs the request-signing calculation. The README says the project uses JavaScript and claims request times in the hundreds of milliseconds. Since that claim comes from the author and the README gives no benchmark procedure, it should not be treated as an independently reproducible performance result.

The dependency structure supports that interpretation. `package.json` names `jsdom` and `tough-cookie`, while `fastify` is listed as a development dependency. Those packages correspond to browser-like JavaScript execution and cookie handling concerns, although the README does not explain exactly where each package is invoked. The repository also includes `demo/xhs.js` and `demo/xhs.py`, confirming that JavaScript and Python examples both exist. The README and package manifest do not explain the exact call path.

Python also needs to execute JavaScript. The README identifies the package as `PyExecJS`, noting that editors may display the import name as `execjs`. A Java runtime is required, while Node.js must support ES13 and be newer than June 2022. Those requirements make the setup dependent on several runtimes whose versions and configuration details are not pinned in the instructions. This is a material constraint for CI workers, containers, and developer laptops where only Python is normally available.

## Running the first xhscrawl demo safely

The repository does not provide a package installation command, release artifact, or documented dependency lock workflow for the Python side. The README directs users to `demo/xhs.py` and says to replace the required parameters and cookie manually. It also links directly to that file rather than publishing its contents. As a result, a reproducible first-use snippet cannot be transcribed without inventing code.

The Node package manifest contains the exact JavaScript dependencies declared by the project:

```json
{
  "name": "xhscrawl",
  "version": "1.0.0",
  "devDependencies": {
    "fastify": "^5.2.1"
  },
  "dependencies": {
    "jsdom": "^26.0.0",
    "tough-cookie": "^5.1.2"
  }
}
```

Do not treat that manifest as a complete Python installation guide. It does not specify the Python package version, Java version, Node.js setup command, environment variables, or the invocation syntax for the demo. To perform the documented first use, prepare Python, PyExecJS, Java, and a compatible Node.js environment, then inspect `demo/xhs.py` and replace only the parameters and cookie specified by that file. The README does not define what successful output looks like, so it also does not provide a verified success criterion. Before making a request, confirm that the selected operation is authorized for the account and that the test will not publish, like, follow, collect, comment, or otherwise change remote state.

## Endpoint coverage and account-side boundaries

The API document list is much broader than the README's description of signature reverse engineering. It names retrieval operations, including note details, note search, user search, comments, user notes, home feed, topic notes, and creator notes. It also lists mutations such as sending a comment, collecting a note, liking a note or comment, following a user, publishing a note, and sending professional-account messages. Login and messaging operations make the authorization surface more sensitive than a read-only scraper.

A developer should therefore separate two evaluation questions. First, does the current signing code produce requests accepted by a chosen web endpoint? Second, is that endpoint appropriate for the intended account and data use? The repository does not document rate limits, retry behavior, pagination rules, error schemas, cookie lifetime, session renewal, or the exact permission required for each operation. The absence of those details makes it unsuitable for an unattended production workflow without separate validation.

The author also advertises an online service for obtaining Xiaohongshu app-side data without providing an account, while stating that users should consider account blocking. That is a separate commercial offering, not an open source API client demonstrated by the repository. Its documentation and recharge page are external resources, and no pricing, availability, or service terms can be verified from the README. Projects that only need app data may find that approach different from xhscrawl, but they must assess the hosted service independently rather than assuming it shares the repository's behavior.

## Where xhscrawl is the wrong tool

The clearest limitation is operational fragility. Xiaohongshu changes its web application and signing behavior, and the README explicitly says its risk controls are becoming stricter. A reverse-engineered signer is tied to the behavior it was written to reproduce, so compatibility can regress outside the author's control. The README links to a changelog but does not summarize it, and there are no GitHub releases. It also does not document a compatibility matrix, automated tests, rollback procedure, or supported Node.js and Python versions beyond broad runtime statements.

Cookie-based operation creates another boundary. The demo requires a manually inserted cookie, which means the request process depends on valid session material and appropriate account permissions. The README does not explain how credentials are stored, redacted, expired, or revoked. It is therefore a poor fit for a shared service unless the integrating team already has a secure approach for session handling and can inspect the complete demo code.

A standard Xiaohongshu API integration would be the better choice when an official or documented interface can satisfy the operation. A conventional crawler backed by exported files or permitted application interfaces would also avoid maintaining signer logic for endpoints that can be read through an approved source. xhscrawl is specifically more relevant when the engineering goal is to study or reproduce Xiaohongshu web request signing, and when there is no supported interface for the required endpoint.

## Maintenance, upgrades, and licensing in xhscrawl

The repository is not archived, and its last push was on 2026-08-15. That date shows recent repository activity, but it does not establish that every endpoint works or that releases are published. There are no GitHub releases, and the README points to `changelog.md` without describing its entries. Upgrade planning must therefore account for possible changes in web signing code, dependencies, endpoints, and demo parameters without relying on semantic release notes.

The maintenance burden falls mainly on the adopter. A change in Xiaohongshu signing rules may require JavaScript updates, while a Node.js or package update may expose compatibility changes in `jsdom`, `tough-cookie`, or the example. Python dependencies are described only by their effective package names, so the project does not present a complete environment specification. Reviewing `changelog.md`, `package.json`, and both demo files before an upgrade is more defensible than treating a repository pull as a routine package update.

The README does not identify a license. That means it does not grant explicit permission to copy, modify, or redistribute the code, and the public repository alone should not be interpreted as a license grant. This review does not offer legal advice. Anyone planning to incorporate the code into a product should first obtain a clear license statement from the repository owner.

## Conclusion

Researchers studying Xiaohongshu request signing can consider xhscrawl after confirming that its current signing logic matches the service behavior they need. Developers should reject it as a production data foundation if they require documented installation, a known license, stable credentials handling, or service guarantees. The first verification should be a narrowly authorized demo using `demo/xhs.py`, a test account, and only an API covered by the account's permissions.

## FAQ

### What problem does submato/xhscrawl solve?

It reverse-engineers the `x-s` signing used by Xiaohongshu web API requests so Python code can work with endpoints that require encrypted request data. The README positions it as a learning and research project.

### What dependencies are required to run xhscrawl?

The README calls for Python, `PyExecJS` with the import name `execjs`, Java, and Node.js newer than June 2022 with ES13 support. The Node manifest also lists `fastify`, `jsdom`, and `tough-cookie`.

### How do I start with the xhscrawl demo?

Open `demo/xhs.py`, replace the required parameters and cookie manually, and run it in the required runtime environment. The README does not provide a complete installation command or a documented success output.

## Sources

- [Issues](https://github.com/submato/xhscrawl/issues)
- [README](https://github.com/submato/xhscrawl/blob/main/README.md)
- [submato/xhscrawl on GitHub](https://github.com/submato/xhscrawl)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/submato-xhscrawl