RSSHub User Guide (DIYgod/RSSHub): guide library

RSSHub turns almost anything on the web into an RSS, Atom, or JSON feed. It is an open-source feed-generation framework with thousands of community-maintained routes — each route knows how to scrape one source (a GitHub repo's issues, a YouTube channel, a Weibo user, a Telegram channel, a news site) and emit a clean, standards-compliant feed your reader can subscribe to.

This guide shows you how to use RSSHub: how feed URLs are structured, how to pick output formats, and how to reshape any feed on the fly with a rich set of universal query parameters (filtering, full-text extraction, item limits, AI summaries, and more). It also covers getting your own instance running in minutes with Docker.

Note

RSSHub is a feed generator, not a feed reader. You point an RSS reader (Folo, Feedly, Miniflux, NetNewsWire, Inoreach, etc.) at an RSSHub feed URL. RSSHub builds the feed; your reader displays it.

1. Quick Start

There are two ways to use RSSHub. Pick based on whether you want zero setup or full control.

Use a public instance (no setup)

The fastest path. Public instances host every route for you. The reference instance is https://rsshub.app. Build a feed URL by appending a route path:

https://rsshub.app/github/issue/DIYgod/RSSHub/open

Paste that URL into your RSS reader's "add subscription" box. You now have a feed of open issues in the DIYgod/RSSHub repository.

Warning

Public instances are shared and best-effort. They may rate-limit, cache aggressively, or lack the credentials some routes need (for example, routes that require a login cookie). For anything you depend on, self-host.

Self-host with Docker (full control)

One command gets you a private instance on port 1200:

docker run -d --name rsshub -p 1200:1200 diygod/rsshub

Verify it is live:

curl http://localhost:1200/healthz

Health check successful

Now build feed URLs against your own host:

http://localhost:1200/github/issue/DIYgod/RSSHub/open

For a production self-host with Redis caching and a headless browser, see the Admin Guide — it covers docker-compose, Cloudflare Workers, Vercel, and Fly.io.

Tip

RSSHub pairs especially well with Folo, an RSS reader built by the same community. Folo can discover RSSHub routes for the page you are viewing. The RSSHub Radar browser extension does the same — it inspects the current website and suggests the matching RSSHub feed.

2. How Feed URLs Work

Every RSSHub feed URL has the same shape:

{instance}/{namespace}/{route-path}

Part	Meaning	Example
`{instance}`	The RSSHub host you are using	`https://rsshub.app` or `http://localhost:1200`
`{namespace}`	The source/site, e.g. one folder of routes	`github`, `youtube`, `weibo`, `telegram`
`{route-path}`	The specific feed within that source, with its parameters filled in	`/issue/DIYgod/RSSHub/open`

A namespace groups all routes for one website. RSSHub ships over 1,500 namespaces covering thousands of individual routes. Within a namespace, each route has a path template with named segments. Take the GitHub "Repo Issues" route, whose path template is:

/issue/:user/:repo/:state?/:labels?

Segments written :name are required parameters — you replace them with a real value.
Segments written :name? are optional — you may omit them (a trailing ? marks optionality).

So the template /issue/:user/:repo/:state?/:labels? produces real URLs like:

/github/issue/DIYgod/RSSHub                 → all open issues (state defaults to "open")
/github/issue/DIYgod/RSSHub/closed          → closed issues
/github/issue/DIYgod/RSSHub/all/bug         → all issues labelled "bug"

Note

Each route documents its own path, parameters, and a working example URL. The canonical, always-current catalog of every route lives at docs.rsshub.app. The same data is served by your instance's API (see Section 8) — useful when you self-host a pinned version.

Finding the route you need

You do not memorize routes. Use one of these:

The documentation site — docs.rsshub.app is searchable by site name.
RSSHub Radar — the browser extension (and its mobile siblings RSSBud for iOS and RSSAid for Android) detects whether the page you are on has a matching route and gives you the URL.
Your instance's home page — open the instance root (http://localhost:1200/) in a browser for the built-in landing page.

3. Choosing an Output Format

By default, RSSHub returns RSS 2.0. Switch formats with the format query parameter. This is appended like any URL query string (?key=value).

`format` value	Output	Content-Type	When to use
(omitted) or `rss`	RSS 2.0 XML	`application/xml`	Default. Works with every reader.
`atom`	Atom 1.0 XML	`application/xml`	Readers that prefer Atom.
`json`	JSON Feed 1.1	`application/feed+json; charset=UTF-8`	Apps and scripts that consume JSON.
`rss3` (or legacy `ums`)	RSS3 JSON	`application/json`	RSS3 network integrations.

Examples:

https://rsshub.app/github/issue/DIYgod/RSSHub?format=atom
https://rsshub.app/github/issue/DIYgod/RSSHub?format=json

Tip

When you combine format with the universal parameters below, separate them with &: …/DIYgod/RSSHub?format=json&limit=10. The first parameter after the path uses ?; every subsequent one uses &.

Note

RSSHub sets an RSS <ttl> (time-to-live, in minutes) on the feed so well-behaved readers know how often to poll. When caching is enabled the <ttl> is derived from the route cache expiry; otherwise it is 1 minute.

4. Universal Feed Parameters — The Power Features

This is what sets RSSHub apart. Every route accepts the same set of query parameters that transform the feed after it is generated — filter it, trim it, translate it, summarize it, or pull in full article text. They work identically whether the route is for GitHub, YouTube, or a tiny blog.

Mix and match freely. All values are URL query parameters.

4.1 Filtering by content

Keep or drop items by matching their title, description, author, and category against a regular expression.

Parameter	Effect
`filter`	Keep only items where title or description or author or category matches.
`filter_title`	Keep only items whose title matches.
`filter_description`	Keep only items whose description matches.
`filter_author`	Keep only items whose author matches.
`filter_category`	Keep only items with a matching category.
`filterout`	Drop items where title or description matches.
`filterout_title`	Drop items whose title matches.
`filterout_description`	Drop items whose description matches.
`filterout_author`	Drop items whose author matches.
`filterout_category`	Drop items with a matching category.
`filter_case_sensitive`	Set to `false` for case-insensitive matching (matching is case-sensitive by default).
`filter_time`	Keep only items published within the last N seconds (based on each item's publish date).

# Only release notes that mention "security"
https://rsshub.app/github/issue/DIYgod/RSSHub?filter=security

# Everything EXCEPT items whose title contains "sponsored", case-insensitive
https://rsshub.app/github/issue/DIYgod/RSSHub?filterout_title=sponsored&filter_case_sensitive=false

# Only items from the last 24 hours (86400 seconds)
https://rsshub.app/github/issue/DIYgod/RSSHub?filter_time=86400

Important

When you supply filter, the field-specific keep filters (filter_title, filter_description, filter_author, filter_category) are ignored — filter takes precedence. The drop filters (filterout*) and filter_time still apply.

Note

The regular-expression engine is configurable by the instance operator. Public/default instances use the RE2 engine (linear-time, no catastrophic backtracking), which supports standard syntax but not certain advanced PCRE features like backreferences. If a complex pattern behaves unexpectedly on a self-hosted instance, check which engine is configured (see the Admin Guide's FILTER_REGEX_ENGINE setting).

4.2 Limiting and ordering

Parameter	Effect
`limit`	Return at most N items (applied after filtering).
`sorted`	Set to `false` to keep the route's original item order. By default items are sorted newest-first by publish date.

# The 5 most recent items
https://rsshub.app/github/issue/DIYgod/RSSHub?limit=5

# Preserve source ordering
https://rsshub.app/github/issue/DIYgod/RSSHub?sorted=false

Tip

limit is the single most useful parameter for busy feeds. It also reduces load on the source site and on shared instances — use it generously.

4.3 Full-text extraction

Many sources only put a summary or the first paragraph in the feed. Add mode=fulltext to have RSSHub fetch each item's link and extract the full article body.

https://rsshub.app/example/blog?mode=fulltext

Warning

Full-text mode fetches every linked page, so feeds build slower and put more load on the origin site. Pair it with limit to keep things reasonable, e.g. ?mode=fulltext&limit=10. Extraction is best-effort: if a page cannot be parsed, RSSHub keeps the original description rather than erroring.

4.4 Shortening items

Parameter	Effect
`brief`	Truncate each item's description to N characters (strips HTML first, appends an ellipsis). `N` must be 100 or greater.

# Trim every item down to a 300-character plain-text teaser
https://rsshub.app/github/issue/DIYgod/RSSHub?brief=300

Caution

A brief value below 100 is rejected with an error. Use brief=100 or higher.

4.5 Translation and conversion

Parameter	Effect
`opencc`	Convert Chinese text between scripts using OpenCC. Pass a conversion config such as `t2s` (Traditional → Simplified) or `s2t` (Simplified → Traditional). Applies to titles and descriptions.
`chatgpt`	Summarize or translate items using a configured OpenAI-compatible model (see note).

# Convert a Traditional-Chinese feed to Simplified
https://rsshub.app/example/zh?opencc=t2s

Note

chatgpt only does anything if the instance operator has configured an OpenAI API key. On instances where it is enabled, it summarizes the description, translates the title, or both — controlled by the operator's settings. Public instances usually leave it off. The AI output is cached per item, so repeated builds are cheap.

4.6 Reading-integration helpers

Parameter	Effect
`tgiv`	Rewrite each item link to a Telegram Instant View URL. Pass your Instant View template hash as the value (`?tgiv=<rhash>`).
`scihub`	Rewrite each item link to its Sci-Hub page (uses the item's DOI when available). Useful for academic-paper feeds.
`image_hotlink_template`	Rewrite image URLs in item content through a proxy template — only when the operator has enabled user-supplied hotlink templates.
`multimedia_hotlink_template`	Same as above for audio/video sources.

Note

image_hotlink_template and multimedia_hotlink_template are ignored unless the operator enabled the feature. They let you route media through an image proxy to defeat referrer-based hotlink protection. See the Admin Guide's anti-hotlink section for the template syntax and the operator-level HOTLINK_TEMPLATE equivalent.

4.7 Putting parameters together

Parameters compose. A realistic "give me a clean, short, recent, English-only digest" URL:

https://rsshub.app/github/issue/DIYgod/RSSHub/all?limit=15&filterout_title=bot&brief=400&format=json

That returns at most 15 items, drops anything whose title contains "bot", trims each description to 400 characters, and serves JSON Feed.

5. Access-Controlled Instances

Some self-hosted instances are locked down so only people who know a key can pull feeds. If an operator has set an access key, you must authenticate every feed request with one of two query parameters:

Parameter	How it works
`key`	The plaintext access key. Simplest, but the key appears in the URL.
`code`	A per-path signature: the MD5 hash of `{request-path}{access-key}`. The key itself never appears in the URL.

# Plaintext key
http://your-instance:1200/github/issue/DIYgod/RSSHub?key=YOUR_ACCESS_KEY

# Signed code (hash of the path + the key)
http://your-instance:1200/github/issue/DIYgod/RSSHub?code=8f9b1c…

Important

The code value is specific to one exact request path. If you change the route path (or add a different route), you must compute a new code. The key value, by contrast, works for any path. Public instances and default self-hosts have no access key, so neither parameter is needed there.

The instance root (/), robots.txt, favicon.ico, and logo.png are always reachable without a key.

6. Everyday Recipes

Tip

These combine the building blocks above. Replace the namespace/route with the one you actually need from docs.rsshub.app; the parameters are universal.

A noise-free GitHub release feed

https://rsshub.app/github/issue/OWNER/REPO/all?filterout_title=dependabot&limit=20

A morning digest of a busy news site

https://rsshub.app/SITE/ROUTE?limit=10&filter_time=43200&brief=500

Last 12 hours (43200 seconds), at most 10 items, 500-character teasers.

Full articles from a summary-only blog, as JSON

https://rsshub.app/BLOG/ROUTE?mode=fulltext&limit=5&format=json

A keyword watch across one source

https://rsshub.app/SITE/ROUTE?filter=kubernetes|k8s&filter_case_sensitive=false

Keep only items mentioning "kubernetes" or "k8s", in any case.

A Simplified-Chinese version of a Traditional-Chinese feed

https://rsshub.app/SITE/ROUTE?opencc=t2s

7. Troubleshooting

RSSHub returns a human-readable error page (or a JSON error when you request ?format=json) with an HTTP status code that tells you what went wrong.

Error: `this route is empty, please check the original site or create an issue`

Cause — The route ran successfully but produced zero items. Usually the source has no content matching your parameters, the upstream page changed its structure, or your filter/filterout removed everything.

Solution — Remove your filter parameters and retry. If it is still empty, open the source site in a browser to confirm it actually has content. If the site has content but the feed is empty, the route may need a fix — report it via a GitHub issue.

Prevention — Test a route without filters first, then add filter* parameters once you confirm items appear.

Error: `The route does not exist or has been deleted.` (HTTP 404)

Cause — The namespace or path does not match any registered route — a typo, a wrong number of path segments, or a route that was removed.

Solution — Re-check the path against the route's documented template and example on docs.rsshub.app. Count the segments: a template like /issue/:user/:repo/:state? needs user and repo at minimum.

Prevention — Copy the example URL from the docs and edit the values, rather than typing paths from memory.

Error: `Authentication failed. Access denied.` (HTTP 403)

Cause — The instance has an access key configured and your request did not include a valid key or code parameter.

Solution — Add ?key=YOUR_ACCESS_KEY (or a correctly computed ?code=) to the URL. Get the key from whoever operates the instance. See Section 5.

Prevention — Store the key in your reader's saved subscription URL so it is always sent.

Error: `This path is currently fetching, please come back later!` (HTTP 503)

Cause — Another request for the same feed is already in flight on the instance. RSSHub serializes identical requests to avoid hammering the source, and yours timed out waiting.

Solution — Wait a moment and refresh. The first request will have populated the cache, so the retry returns instantly.

Prevention — Let your reader poll on a normal schedule rather than refreshing repeatedly by hand.

Error pages with HTTP 503 and an upstream message

Cause — The route reached the source site but the source returned an error, timed out, or blocked the request (rate limiting, anti-bot, expired credentials).

Solution — Retry later. If it persists on a public instance, the instance may be rate-limited by the source; try self-hosting with appropriate credentials. If it persists on your self-hosted instance, the route may require configuration (an API token or cookie) — check the route's docs and the Admin Guide's configuration reference.

Prevention — For sources that require login, self-host and supply the route's credentials via environment variables.

Invalid parameter `brief`

Cause — You passed brief with a value below 100 (or a non-numeric value).

Solution — Use brief=100 or any larger integer.

A regex filter does nothing or errors on a self-hosted instance

Cause — The instance's regex engine (re2 by default) does not support a feature your pattern uses (e.g. backreferences), or the pattern is invalid.

Solution — Simplify the pattern to standard regex syntax. Operators can switch the engine to regexp (see Admin Guide), but re2 is the safe default.

8. Discovering Routes Programmatically

Every RSSHub instance exposes a small public JSON API describing its own routes — handy for building tools, dashboards, or your own route picker. These endpoints live under /api and need no authentication beyond the instance's normal access key (if any).

Endpoint	Returns
`GET /api/namespace/all`	Every namespace and its routes, with parameters and examples.
`GET /api/namespace/:namespace`	One namespace's routes (e.g. `/api/namespace/github`).
`GET /api/category/:category`	Routes grouped under a category (e.g. `programming`).
`GET /api/radar/rules/all`	All RSSHub Radar detection rules.
`GET /api/radar/rules/:domain`	Radar rules for one domain.
`GET /api/route/status`	Route health/status data.
`GET /api/openapi.json`	The full OpenAPI 3.1 specification for the API.
`GET /api/reference`	An interactive, browsable API reference (Scalar UI).

# List every route GitHub exposes on a public instance
curl https://rsshub.app/api/namespace/github

Tip

GET /api/reference opens a friendly "try it" UI in the browser — the easiest way to explore the API without reading the spec.

9. Frequently Asked Questions

Q: Do I need to install anything to use RSSHub? No. Use a public instance like https://rsshub.app and just paste route URLs into your reader. Install (via Docker) only if you want privacy, reliability, or routes that need credentials.

Q: Is RSSHub free? Yes. RSSHub is open source under the AGPL-3.0 license. Public instances are run by volunteers; self-hosting is free aside from your own hosting costs.

Q: A route needs my login cookie. Can I use it on the public instance? You should not put your private cookies into a shared public instance. Self-host and supply the cookie via the route's environment variable (see the Admin Guide's configuration reference). That keeps your credentials on your own server.

Q: Why is my feed sometimes a few minutes stale? RSSHub caches route output (5 minutes by default on a typical instance) so it does not re-scrape the source on every request. This is intentional and keeps both RSSHub and the source healthy. The RSS <ttl> reflects the cache window.

Q: How do I get only the latest few items? Add ?limit=N, e.g. ?limit=5. It applies after any filtering.

Q: Can I keep only items matching a keyword? Yes — ?filter=KEYWORD. Match a specific field with filter_title, filter_description, filter_author, or filter_category. Drop matches instead with the filterout* variants.

Q: The feed only has summaries. Can I get full articles? Add ?mode=fulltext. RSSHub fetches each linked page and extracts the body. Combine with ?limit= so the build stays fast.

Q: What output formats can I get? RSS (default), Atom (?format=atom), JSON Feed (?format=json), and RSS3 (?format=rss3). See Section 3.

Q: How do I translate a Chinese feed? Use ?opencc=t2s (Traditional → Simplified) or ?opencc=s2t (Simplified → Traditional).

Q: My reader says the feed is empty, but the website has new posts. What now? The route may have broken because the source site changed. Remove any filters first; if still empty, report it on GitHub Issues.

Q: Can I require a key so only I can use my instance? Yes — that is an operator setting (ACCESS_KEY). Once set, every feed URL needs ?key= or ?code=. See Section 5 and the Admin Guide.

Q: How do I find the route for a specific website? Search docs.rsshub.app, or install the RSSHub Radar browser extension, which detects the route for whatever page you are on.

Q: How many sites does RSSHub support? Over 1,500 namespaces, each with one or more routes — thousands of feeds in total, growing constantly through community contributions.

Q: Can I read the routes via an API instead of the docs site? Yes. Hit GET /api/namespace/all (or /api/reference for an interactive browser). See Section 8.

Q: Does RSSHub work on Cloudflare Workers / Vercel / Fly.io? Yes — those are deployment options for operators. As a user you just get a feed URL; how it is hosted is transparent to you. See the Admin Guide for deployment.