FreshRSS: a self-hosted RSS aggregator with XPath scraping and a CLI

What FreshRSS solves, and for whom

FreshRSS is a self-hosted RSS feed aggregator written in PHP. The problem it addresses is straightforward: reading many feeds without handing your subscription list and reading history to a commercial service. The README describes it as a multi-user application with an anonymous reading mode, custom tags, an API for mobile clients and a command-line interface. That combination points at a specific audience: someone with a server already running, who wants several people reading from the same installation, and who is comfortable maintaining a PHP application. The README also notes it has been translated into many languages, and that it works on a Raspberry Pi 1 with response time under a second in a test with 150 feeds and 22k articles. That is the vendor's own testing note, not an independent measurement, but it sets the expectation that the footprint is small. The project is licensed AGPL-3.0 and the README states it comes with absolutely no warranty.

How FreshRSS fetches, stores and serves articles

The architecture is a PHP web application plus a database. The README lists PostgreSQL 10+, SQLite, MariaDB 10.6+ or MySQL 8.0+ as the storage options, and PHP 8.1+ with a set of required extensions. Only the p/ folder is meant to be exposed to the web; the README warns that data/ holds all personal data and is a bad idea to expose. That split is the core of the deployment model: application code and user data live outside the document root, and constants.php defines access to the application folder.

Fetching has two paths. For normal feeds, FreshRSS polls RSS and Atom sources. For sources that publish no feed at all, it supports basic web scraping based on XPath, and it also supports JSON documents. This is the feature that separates it from aggregators that only consume feeds: you point it at an HTML page and describe, in XPath, where the items are. It is explicitly described as basic, so treat it as a fallback for simple, stable page structures rather than a general scraping framework. On top of polling, WebSub support lets compatible sources such as Friendica, WordPress, Blogger and Medium push updates instead of waiting for the next poll. The README also mentions resharing selections of articles by HTML, RSS and OPML through user queries, which is how a FreshRSS instance can itself become a feed source for someone else.

Installing FreshRSS with Docker and adding your first feed

The README lists automated install options including a Docker image in the Docker/ folder, Yunohost, Cloudron, Elestio, PikaPods, Zeabur and a Hostinger compose template. The repository ships a docker-compose.yml under Docker/freshrss/. For a manual install the README gives five steps: get the code with git or the archive, put it on your server exposing only ./p/, give the webserver user write access to ./data/, then open it in a browser and follow the installation process, or use the CLI.

If you are developing or just want to poke at it locally, the Makefile exposes a start target that runs the published image against your working copy and publishes port 8080 by default:

make start

The Makefile sets PORT ?= 8080 and runs the container with FRESHRSS_ENV=development, mounting the repository at /var/www/FreshRSS. After the container is up, open http://localhost:8080 in a browser and complete the installation form. When you are done, the same Makefile stops the container and removes its network:

make stop

For a manual install rather than Docker, the README points at the archive download and the browser installer, and notes that advanced settings live in config.default.php and are changed in data/config.php. Two operational details from the README are easy to miss. On Apache, enable AllowEncodedSlashes for better compatibility with mobile clients. And if you plan to customize paths, look at constants.php first, because it defines access to the application folder.

The client and extension story, and what the README leaves open

FreshRSS is not only a web interface. The README states there is an API for mobile clients and a Command-Line Interface documented in cli/README.md, and the repository has an extensions/ directory for further tuning. Different login methods are supported: web form with an anonymous option, HTTP Authentication compatible with proxy delegation, and OpenID Connect. That range matters if the instance sits behind a reverse proxy or an identity provider.

What the README does not do is name specific mobile applications or walk through extension installation. It links to a developer documentation index and to the user documentation, and the search phrases people use about this project include Android clients and extension installation, so those answers live in the linked docs rather than in the README itself. Likewise, the README does not document rollback, backup or restore procedures; it points at the administrator documentation for maintenance tasks. If your decision depends on a documented upgrade path, that is the page to read before deploying, not this article.

Where FreshRSS is the wrong choice

The first limitation is environmental. FreshRSS requires PHP 8.1+ with cURL, DOM, JSON, XML, session and ctype, plus a database driver among PDO_PGSQL, PDO_SQLite and PDO_MySQL, and a web server among Apache 2.4+, nginx and lighttpd. If you want a single static binary you can drop on a machine, this is not that. If you do not want to run a PHP runtime and a database at all, every maintenance task here is one you have taken on yourself.

The second is the scraping feature's scope. The README calls it basic and based on XPath. Sites that render content client-side, change markup often, or require authentication will not be handled well by a static XPath expression, and the README does not present it as a general-purpose scraper. The third is the absence of published operational guarantees in the README: no rollback procedure, no backup guide, no stated support window. The project does publish releases regularly, and the most recent listed releases are 1.29.1 on 2026-05-20 and 1.29.0 on 2026-05-10, with the README saying new versions are released every two to three months. That is a release cadence, not a support commitment, and the README does not make one.

FreshRSS compared with Miniflux

The most common comparison people search for is FreshRSS against Miniflux. The difference is in what the application is built from and what it assumes about you. FreshRSS is PHP with a choice of PostgreSQL, MariaDB, MySQL or SQLite, a web installer, a multi-user model with an anonymous reading mode, custom tags, XPath scraping for feedless sites, WebSub push, resharing via user queries, and several login methods including OpenID Connect. Miniflux is a different stack and a different set of defaults, and this material does not describe it, so the honest comparison is narrow: if your existing infrastructure is PHP and you want the scraping and multi-user features in the same package, FreshRSS matches that shape. If you want to avoid a PHP runtime entirely, that is the axis on which you should compare them, not a feature checklist. The same reasoning applies to the other names people search alongside it, such as Tiny Tiny RSS and CommaFeed: the deciding question is which runtime and database you are willing to operate, because that is the cost you keep paying after installation.

Maintenance cost, releases and the AGPL-3.0 licence

The last push to the repository was on 2026-05-20, which is the same date as the 1.29.1 release. The README states that new versions are released every two to three months, and the listed releases are consistent with that: 1.28.1 on 2026-01-25, 1.29.0 on 2026-05-10, 1.29.1 on 2026-05-20. The project is not archived. For a self-hosted application, that cadence means you should expect to apply updates a few times a year, and the README does not describe how to roll one back if it goes wrong.

The licence is GNU AGPL 3. The practical consequence of AGPL-3.0 for a self-hosted web application is that if you modify the code and let users interact with it over a network, the licence's source-disclosure terms can reach your modified version. That is a statement about what the licence says, not legal advice; if you plan to fork FreshRSS and run it as a service, read LICENSE.txt and the licence text itself, and take your own advice on it. Running an unmodified copy for yourself or your household is the case the licence is plainly designed to permit.

Editorial conclusion

Adopt FreshRSS if you want a multi-user, self-hosted reader with an API for mobile clients and XPath scraping for sites that publish no feed, and you are willing to run PHP 8.1+ with PostgreSQL, MariaDB, MySQL or SQLite. Skip it if you want a single static binary or a hosted service with no server to patch. Before committing, verify that your PHP build has the required extensions (cURL, DOM, JSON, XML, session, ctype) plus a PDO driver, and read the AGPL-3.0 licence text if you plan to modify and redistribute it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes