2018-12-21 12:26:20 +01:00
[](https://liberapay.com/FreshRSS/donate)
2017-09-22 12:13:46 +02:00
2021-03-15 00:00:25 +01:00
* Read this document on [github.com/FreshRSS/FreshRSS/ ](https://github.com/FreshRSS/FreshRSS/blob/edge/README.md ) to get the correct links and pictures.
2014-08-23 15:35:46 +02:00
* [Version française ](README.fr.md )
2013-06-23 19:14:49 +02:00
# FreshRSS
2021-03-15 00:00:25 +01:00
2022-11-20 14:47:27 +01:00
FreshRSS is a self-hosted RSS feed aggregator.
2014-01-01 17:03:51 +01:00
2018-12-04 20:00:24 +01:00
It is lightweight, easy to work with, powerful, and customizable.
2014-01-01 17:03:51 +01:00
2018-12-16 17:02:03 +01:00
It is a multi-user application with an anonymous reading mode. It supports custom tags.
2017-12-21 17:21:41 +01:00
There is an API for (mobile) clients, and a [Command-Line Interface ](cli/README.md ).
2018-12-16 17:02:03 +01:00
2023-11-14 23:28:01 +01:00
Thanks to the [WebSub ](https://freshrss.github.io/FreshRSS/en/users/WebSub.html ) standard,
2023-11-08 20:24:24 +01:00
FreshRSS is able to receive instant push notifications from compatible sources, such as [Friendica ](https://friendi.ca ), [WordPress ](https://wordpress.org/plugins/pubsubhubbub/ ), Blogger, Medium, etc.
2018-12-16 17:02:03 +01:00
2024-02-26 09:01:03 +01:00
FreshRSS natively supports basic [Web scraping ](https://freshrss.github.io/FreshRSS/en/users/11_website_scraping.html ),
based on [XPath ](https://www.w3.org/TR/xpath-10/ ), for Web sites not providing any RSS / Atom feed.
Also supports JSON documents.
FreshRSS offers the ability to [reshare selections of articles by HTML, RSS, and OPML ](https://freshrss.github.io/FreshRSS/en/users/user_queries.html ).
2022-02-28 20:22:43 +01:00
2023-06-12 10:22:46 +02:00
Different [login methods ](https://freshrss.github.io/FreshRSS/en/admins/09_AccessControl.html ) are supported: Web form (including an anonymous option), HTTP Authentication (compatible with proxy delegation), OpenID Connect.
Finally, FreshRSS supports [extensions ](#extensions ) for further tuning.
2013-06-23 19:14:49 +02:00
2021-10-23 13:43:24 +02:00
* Official website: < https: // freshrss . org >
2023-11-14 23:28:01 +01:00
* Demo: < https: // demo . freshrss . org >
2017-12-21 17:21:41 +01:00
* License: [GNU AGPL 3 ](https://www.gnu.org/licenses/agpl-3.0.html )
2013-06-23 19:14:49 +02:00
2017-12-21 17:21:41 +01:00
2013-07-02 23:41:33 +02:00
2022-11-20 14:47:27 +01:00
## Feedback and contributions
2021-03-15 00:00:25 +01:00
2022-11-20 14:47:27 +01:00
Feature requests, bug reports, and other contributions are welcome. The best way is to [open an issue on GitHub ](https://github.com/FreshRSS/FreshRSS/issues ).
We are a friendly community.
2023-05-28 18:03:34 +02:00
To facilitate contributions, the [following option ](.devcontainer/README.md ) is available:
2022-11-20 14:47:27 +01:00
[](https://github.com/codespaces/new?hide_repo_select=true& ref=edge& repo=6322699)
## Screenshot
2014-08-23 15:13:01 +02:00
2018-12-16 21:56:55 +01:00
2022-11-20 14:47:27 +01:00
## Disclaimer
FreshRSS comes with absolutely no warranty.
2018-12-16 21:56:55 +01:00
# [Documentation](https://freshrss.github.io/FreshRSS/en/)
2021-03-15 00:00:25 +01:00
2018-12-16 21:56:55 +01:00
* [User documentation ](https://freshrss.github.io/FreshRSS/en/users/02_First_steps.html ), where you can discover all the possibilities offered by FreshRSS
* [Administrator documentation ](https://freshrss.github.io/FreshRSS/en/admins/01_Index.html ) for detailed installation and maintenance related tasks
2021-07-23 17:30:59 +02:00
* [Developer documentation ](https://freshrss.github.io/FreshRSS/en/developers/01_Index.html ) to guide you in the source code of FreshRSS and to help you if you want to contribute
2019-12-03 22:56:57 +01:00
* [Contributor guidelines ](https://freshrss.github.io/FreshRSS/en/contributing.html ) for those who want to help improve FreshRSS
2018-12-16 21:56:55 +01:00
2014-08-23 15:13:01 +02:00
# Requirements
2021-03-15 00:00:25 +01:00
2021-08-20 14:51:28 +02:00
* A recent browser like Firefox / IceCat, Edge, Chromium / Chrome, Opera, Safari.
2018-12-16 21:56:55 +01:00
* Works on mobile (except a few features)
2014-08-23 15:13:01 +02:00
* Light server running Linux or Windows
2016-02-28 13:40:15 +01:00
* It even works on Raspberry Pi 1 with response time under a second (tested with 150 feeds, 22k articles)
2023-10-31 12:27:32 +01:00
* A web server: Apache2.4+ (recommended), nginx, lighttpd (not tested on others)
2023-10-30 20:47:27 +01:00
* PHP 7.4+
2023-10-31 23:37:16 +01:00
* Required extensions: [cURL ](https://www.php.net/curl ), [DOM ](https://www.php.net/dom ), [JSON ](https://www.php.net/json ), [XML ](https://www.php.net/xml ), [session ](https://www.php.net/session ), [ctype ](https://www.php.net/ctype )
* Recommended extensions: [PDO_SQLite ](https://www.php.net/pdo-sqlite ) (for export/import), [GMP ](https://www.php.net/gmp ) (for API access on 32-bit platforms), [IDN ](https://www.php.net/intl.idn ) (for Internationalized Domain Names), [mbstring ](https://www.php.net/mbstring ) (for Unicode strings), [iconv ](https://www.php.net/iconv ) (for charset conversion), [ZIP ](https://www.php.net/zip ) (for import/export), [zlib ](https://www.php.net/zlib ) (for compressed feeds)
* Extension for database: [PDO_PGSQL ](https://www.php.net/pdo-pgsql ) or [PDO_SQLite ](https://www.php.net/pdo-sqlite ) or [PDO_MySQL ](https://www.php.net/pdo-mysql )
* PostgreSQL 9.5+ or SQLite or MySQL 5.5.3+ or MariaDB 5.5+
2014-08-23 15:13:01 +02:00
2022-11-20 14:47:27 +01:00
# [Installation](https://freshrss.github.io/FreshRSS/en/admins/03_Installation.html)
2017-04-05 00:43:08 +02:00
2019-12-15 14:08:49 +01:00
The latest stable release can be found [here ](https://github.com/FreshRSS/FreshRSS/releases/latest ). New versions are released every two to three months.
2021-03-15 00:00:25 +01:00
If you want a rolling release with the newest features, or want to help testing or developing the next stable version, you can use [the `edge` branch ](https://github.com/FreshRSS/FreshRSS/tree/edge/ ).
2018-12-16 22:06:17 +01:00
2018-12-16 21:56:55 +01:00
## Automated install
2021-03-15 00:00:25 +01:00
2022-05-07 14:28:28 +02:00
* [<img src="https://www.docker.com/wp-content/uploads/2022/03/horizontal-logo-monochromatic-white.png" width="200" alt="Docker" /> ](./Docker/ )
2018-12-16 21:56:55 +01:00
* [](https://install-app.yunohost.org/?app=freshrss)
* [](https://cloudron.io/button.html?app=org.freshrss.cloudronapp)
2022-05-07 14:28:28 +02:00
* [](https://www.pikapods.com/pods?run=freshrss)
2018-12-16 21:56:55 +01:00
## Manual install
2021-03-15 00:00:25 +01:00
1. Get FreshRSS with git or [by downloading the archive ](https://github.com/FreshRSS/FreshRSS/archive/latest.zip )
2018-12-16 14:33:59 +01:00
2. Put the application somewhere on your server (expose only the `./p/` folder to the Web)
2018-12-04 20:00:24 +01:00
3. Add write access to the `./data/` folder for the webserver user
2014-08-23 15:13:01 +02:00
4. Access FreshRSS with your browser and follow the installation process
2017-12-21 17:21:41 +01:00
* or use the [Command-Line Interface ](cli/README.md )
2018-12-04 20:00:24 +01:00
5. Everything should be working :) If you encounter any problems, feel free to [contact us ](https://github.com/FreshRSS/FreshRSS/issues ).
6. Advanced configuration settings can be found in [config.default.php ](config.default.php ) and modified in `data/config.php` .
2017-12-21 17:21:41 +01:00
7. When using Apache, enable [`AllowEncodedSlashes` ](https://httpd.apache.org/docs/trunk/mod/core.html#allowencodedslashes ) for better compatibility with mobile clients.
2014-08-23 15:13:01 +02:00
2019-12-03 22:56:57 +01:00
More detailed information about installation and server configuration can be found in [our documentation ](https://freshrss.github.io/FreshRSS/en/admins/03_Installation.html ).
2017-12-02 13:43:28 +01:00
2022-11-20 14:47:27 +01:00
# Advice
2021-03-15 00:00:25 +01:00
2018-12-04 20:00:24 +01:00
* For better security, expose only the `./p/` folder to the Web.
2015-01-16 23:31:55 +01:00
* Be aware that the `./data/` folder contains all personal data, so it is a bad idea to expose it.
2018-12-04 20:00:24 +01:00
* The `./constants.php` file defines access to the application folder. If you want to customize your installation, look here first.
2017-04-01 18:55:40 +02:00
* If you encounter any problem, logs are accessible from the interface or manually in `./data/users/*/log*.txt` files.
* The special folder `./data/users/_/` contains the part of the logs that are shared by all users.
2018-12-16 14:33:59 +01:00
2021-10-23 13:43:24 +02:00
# FAQ
2021-03-15 00:00:25 +01:00
2018-12-04 20:00:24 +01:00
* The date and time in the right-hand column is the date declared by the feed, not the time at which the article was received by FreshRSS, and it is not used for sorting.
2018-12-16 14:33:59 +01:00
* In particular, when importing a new feed, all of its articles will appear at the top of the feed list regardless of their declared date.
2014-01-03 18:29:40 +01:00
2016-10-05 22:06:53 +02:00
2018-05-24 21:53:47 +02:00
# Extensions
2021-03-15 00:00:25 +01:00
2016-12-21 16:47:20 +01:00
FreshRSS supports further customizations by adding extensions on top of its core functionality.
2018-05-24 21:53:47 +02:00
See the [repository dedicated to those extensions ](https://github.com/FreshRSS/Extensions ).
# APIs & native apps
2022-02-27 21:50:28 +01:00
FreshRSS supports access from mobile / native apps for Linux, Android, iOS, Windows and macOS, via two distinct APIs:
2024-05-24 09:21:28 +02:00
[Google Reader API ](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html ) (best),
and [Fever API ](https://freshrss.github.io/FreshRSS/en/developers/06_Fever_API.html ) (limited features and less efficient).
2020-05-15 18:20:29 +02:00
| App | Platform | Free Software | Maintained & Developed | API | Works offline | Fast sync | Fetch more in individual views | Fetch read articles | Favourites | Labels | Podcasts | Manage feeds |
|:--------------------------------------------------------------------------------------|:-----------:|:-------------------------------------------------------------:|:----------------------:|:----------------:|:-------------:|:---------:|:------------------------------:|:-------------------:|:----------:|:------:|:--------:|:------------:|
2022-03-06 21:32:00 +01:00
| [News+ ](https://github.com/noinnion/newsplus/blob/master/apk/NewsPlus_202.apk ) with [Google Reader extension ](https://github.com/noinnion/newsplus/blob/master/apk/GoogleReaderCloneExtension_101.apk ) | Android | [Partially ](https://github.com/noinnion/newsplus/blob/master/extensions/GoogleReaderCloneExtension/src/com/noinnion/android/newsplus/extension/google_reader/ ) | 2015 | GReader | ✔️ | ⭐⭐⭐ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
2022-09-20 21:48:01 +02:00
| [FeedMe ](https://play.google.com/store/apps/details?id=com.seazon.feedme )* | Android | ➖ ➖ ➖
| [EasyRSS ](https://github.com/Alkarex/EasyRSS ) | Android | [✔️ ](https://github.com/Alkarex/EasyRSS ) | ✔️ | GReader | Bug | ⭐⭐ | ➖ ➖ ➖ ➖ ➖
| [Readrops ](https://github.com/readrops/Readrops ) | Android | [✔️ ](https://github.com/readrops/Readrops ) | ✔️✔️ | GReader | ✔️ | ⭐⭐⭐ | ➖ ➖ ➖ ➖ ➖
| [Fluent Reader Lite ](https://hyliu.me/fluent-reader-lite/ ) | Android, iOS| [✔️ ](https://github.com/yang991178/fluent-reader-lite ) | ✔️✔️ | GReader, Fever | ✔️ | ⭐⭐⭐ | ➖ ➖ ➖ ➖ ➖
| [FocusReader ](https://play.google.com/store/apps/details?id=allen.town.focus.reader ) | Android | ➖ ➖ ➖ ➖
2024-01-21 14:03:45 +01:00
| [Read You ](https://github.com/Ashinch/ReadYou/ ) | Android | [✔️ ](https://github.com/Ashinch/ReadYou/ ) | [Work in progress ](https://github.com/Ashinch/ReadYou/discussions/542 ) | GReader, Fever | ➖ ➖ ➖ ➖
2024-01-21 13:56:08 +01:00
| [ChristopheHenry ](https://gitlab.com/christophehenry/freshrss-android ) | Android | [✔️ ](https://gitlab.com/christophehenry/freshrss-android ) | Work in progress | GReader | ✔️ | ⭐⭐ | ➖ ➖ ➖ ➖
2022-09-20 21:48:01 +02:00
| [Fluent Reader ](https://hyliu.me/fluent-reader/ ) | Windows, Linux, macOS| [✔️ ](https://github.com/yang991178/fluent-reader ) | ✔️✔️ | GReader, Fever | ✔️ | ⭐ | ➖ ➖ ➖ ➖
2023-11-16 13:19:01 +01:00
| [RSS Guard ](https://github.com/martinrotter/rssguard ) | Windows, GNU/Linux, macOS, OS/2 | [✔️ ](https://github.com/martinrotter/rssguard ) | ✔️✔️ | GReader | ✔️ | ⭐⭐ | ➖
2022-10-16 14:25:25 +02:00
| [NewsFlash ](https://gitlab.com/news-flash/news_flash_gtk ) | GNU/Linux | [✔️ ](https://gitlab.com/news-flash/news_flash_gtk ) | ✔️✔️ | GReader, Fever | ➖ ➖ ➖ ➖
2022-02-27 21:50:28 +01:00
| [Newsboat 2.24+ ](https://newsboat.org/ ) | GNU/Linux, macOS, FreeBSD | [✔️ ](https://github.com/newsboat/newsboat/ ) | ✔️✔️ | GReader | ➖ ➖ ➖ ➖
| [Vienna RSS ](http://www.vienna-rss.com/ ) | macOS | [✔️ ](https://github.com/ViennaRSS/vienna-rss ) | ✔️✔️ | GReader | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ | ❔ |
2024-01-21 13:56:08 +01:00
| [Readkit ](https://apps.apple.com/app/readkit-read-later-rss/id1615798039 ) | iOS, macOS | ➖ ➖ ➖
2022-09-20 21:48:01 +02:00
| [Reeder ](https://www.reederapp.com/ )* | iOS, macOS | ➖ ➖ ➖ ➖
2022-08-22 23:18:50 +02:00
| [lire ](https://lireapp.com/ ) | iOS, macOS | ➖
2020-05-15 18:20:29 +02:00
| [Unread ](https://apps.apple.com/app/unread-2/id1363637349 ) | iOS | ➖ ➖ ➖ ➖
| [Fiery Feeds ](https://apps.apple.com/app/fiery-feeds-rss-reader/id1158763303 ) | iOS | ➖ ➖ ➖ ➖
2022-02-27 21:50:28 +01:00
| [Netnewswire ](https://ranchero.com/netnewswire/ ) | iOS, macOS | [✔️ ](https://github.com/Ranchero-Software/NetNewsWire ) | Work in progress | GReader | ✔️ | ❔ | ❔ | ❔ | ✔️ | ➖
2016-12-21 16:47:20 +01:00
2022-06-13 21:00:55 +02:00
\* Install and enable the [GReader Redate extension ](https://github.com/javerous/freshrss-greader-redate ) to have the correct publication date for feed articles if you are using Reeder 4 or FeedMe. (No longer required for Reeder 5)
2020-11-02 23:25:16 +01:00
2014-08-23 15:13:01 +02:00
# Included libraries
2021-03-15 00:00:25 +01:00
2017-12-21 17:21:41 +01:00
* [SimplePie ](https://simplepie.org/ )
2022-06-16 20:25:31 +02:00
* [MINZ ](https://framagit.org/marienfressinaud/MINZ )
2017-09-26 22:20:25 +02:00
* [php-http-304 ](https://alexandre.alapetite.fr/doc-alex/php-http-304/ )
2023-01-18 10:12:21 +01:00
* [lib_opml ](https://framagit.org/marienfressinaud/lib_opml )
2022-03-16 15:10:41 +01:00
* [PhpGt/CssXPath ](https://github.com/PhpGt/CssXPath )
2019-08-15 17:19:12 +02:00
* [PHPMailer ](https://github.com/PHPMailer/PHPMailer )
2021-10-16 12:00:07 +02:00
* [Chart.js ](https://www.chartjs.org )
2014-01-11 15:41:58 +01:00
Decouple scrolling of feeds and articles (#2117)
* Remove Sticky Kit
Remove sticky-kit, as functionality is unsuitable for separate scrolling.
* Remove sticky-kit load in main.js
Further removing the sticky-kit kruft
* Finish removal of references to Sticky-kit
* CSS Changes to template for Independent Scrolling
* Addition of JS and supporting CSS and html
* More CSS fixes to establish expected behavior
Should be able to scroll navbar without it being in sticky mode now.
* Fix typo in main.js
sortcut.js -> shortcut.js
* Fix unexpected tree scrolling behavior
* Change name of generic JS function
* Improve sticky-aside
* CSS changes in themes to accommodate independent Scroll
In themes where .aside's width is not the standard 300px, .tree's width must be specified to be equal to .aside
* Remove Sticky-Kit from README files
* Updates to Sticky-Aside
* Update Template to fix screwup
* Make Recalculating height actually work
* Let sidebar fill height if nav buttons aren't visible
* Make accommodating for nav buttons actually work
* update Swage theme for Independent Scroll feature
* Integrate sticky_aside into main.js
* Add Simple Scrollbar
* Patch scrollbar color for themes with dark colored asides
* Increase Visibility of scrollbar on Dark Themes
* Improve async loading, events, and performance
* CSS typo
* Fix double scrollbar on mobile
* Fix regression causing sticky to not be removed
* No $ for non-jQuery variables
* Fix strange condition + option for nice scrollbar
* Initial attempt to use css sticky
* Add stickyfill
* make the correct element sticky
* re-add incorrectly removed sidebar code
* Continue fixing mistaken deletions
* decrease frequency of recalc
* use minified version of simple-scrollbar.
* Load stickyfill instead of injecting
* put recalc back where it belongs
* re-remove script injector
* remove padding
bottom padding was causing the last item in the feed to be hidden under the nav buttons
* Manual merge of css_scrollbar
Add auto-detection of -webkit-scrollbar-thumb, otherwise fall back to
simple-scrollbar.js
* Fix Regression
Sticky recalc is still needed when using css scrollbars
* Replace method of closing dropdowns
Changed from an overlay href to a javascript solution, for better compatibility
* Remove Treepadding
Treepadding was causing dropdown menus at the bottom of the tree to be obscured.
* Undo unnecessary move of dropdown-target
* Move Dropdown Handler to a sensibleish place
* Fix light Scrollbar color not picking up on Firefox
* Minor syntax
* Minor Clarification of CSS/ patch BlueLagoon
* Change logic for native WebKit scrollbar detection
Fix
https://github.com/FreshRSS/FreshRSS/pull/2117#issuecomment-444251419
Tested with Firefox 63, Firefox 65, Chrome 71, IE11, Edge 42
* Fixes for other views
E.g. reader view
* Cleaner way of generating hash for dropdowns
* Make dropdown-toggle an actual toggle
* Prepare for CSS Scrollbars Module Level 1
* Fix regression causing my labels dropdown not to appear
* remove unneeded dropdown-close css rule
* Re-apply some lost changes
https://github.com/FreshRSS/FreshRSS/pull/2117/commits/3c509989e890b88852e52c67c1c5507d1e0bf28c
* Add standard scrollbar compatibility
E.g. Firefox 64+
* Make All dropdowns click-to-close
* Remove BlueLagoon template
* Try to fix Firefox
https://github.com/FreshRSS/FreshRSS/pull/2117#discussion_r239539984
* Add CSS rules necessary for consistent function of scrollbar in Firefox
* Use inheritance to determine width
* Use overlay scrollbar where possible
* Test Reduced Listener
* Fix Firefox 62
And show subtle scrollbar even when not hovering
* Add margin at bottom
To allow opening the menus
https://github.com/FreshRSS/FreshRSS/pull/2117#issuecomment-444571218
* Minor - tab correction
* Spaces -> tabs
* Remove unneeded inheritance
* Fix indenting
* Revert bad merge
* Messy WIP to make dropdowns work
* Style Cleanup
* Break it down
* Lets try a move-it move-it
* Update p/scripts/main.js
Co-Authored-By: pattems <patrick@crandol.com>
* Update p/themes/BlueLagoon/BlueLagoon.css
Co-Authored-By: pattems <patrick@crandol.com>
* separate ALL THE THINGS
* erroneous commas
* and to or
* removing double condition that doesn't do what I want
* More breaking down
* fix var
* Fix variable name again
* Remove magic number
https://github.com/FreshRSS/FreshRSS/pull/2117#discussion_r240052598
* Suuuuper inelegant solution for dropdowns
* lets try that again
* Inelegant Fix For Dropdowns
Now with 100% more working dropdowns
* Make sidebar dropdowns work correctly?
* Fix reversion
* Make JS scrollbar always visible
* Remove unneeded CSS
Added early in this pull request, didn't get pulled out when it was obsolete
* Fix CSS removal I missed
* CSS comment update/consistency for dark themes
* Clean Up Duplicate code
* Make dropdowns properly hide
Downside: Can no longer click on header/nav buttons to close
* Strip unneeded if statement
* jshint -W018
https://github.com/FreshRSS/FreshRSS/pull/2117#discussion_r240392851
* Half-reversion to old dropdown
* make overlay href scale to sidebar width
* remove init of nonexistent method
* remove trailing tabs
* move #close href where it belongs in index.phtml
* Revert all changes to index.phtml
* remove whitespace
accidentally added in last commit
* Move var's in init_column categories
* Finish putting old style dropdowns back
* Make CSS changes to use support statements
* Cleanup Whitespace
* re-add missing class
* spaces -> tabs in main.js
* tabs -> spaces css
* Minor whitespace
* Cleanup per @Alkarex
* Second attempt to add bottom margin
https://github.com/FreshRSS/FreshRSS/pull/2117#discussion_r240820901
* Fix error in IE11
* Simple-scrollbar color match for dark themes
2018-12-12 12:04:31 +01:00
## Only for some options or configurations
2021-03-15 00:00:25 +01:00
2014-01-11 15:38:29 +01:00
* [bcrypt.js ](https://github.com/dcodeIO/bcrypt.js )
2017-12-21 17:21:41 +01:00
* [phpQuery ](https://github.com/phpquery/phpquery )
2023-05-11 13:08:23 +02:00
# Alternatives
2023-06-13 22:16:27 +02:00
If FreshRSS does not suit you for one reason or another, here are alternative solutions to consider:
2023-05-11 13:08:23 +02:00
* [Kriss Feed ](https://tontof.net/kriss/feed/ )
* [Leed ](https://github.com/LeedRSS/Leed )
* [And more… ](https://alternativeto.net/software/freshrss/ ) (but if you like FreshRSS, give us a vote!)
