Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A basic terminal RSS feed reader written in Python 3.




Install via pip with pip3 install tread or download the source and run python3 install.


  • Python 3.5
  • curses (included with Python 3.5 on *nix systems)
  • sqlalchemy
  • pyyaml
  • python-dateutil
  • requests
  • beautifulsoup4
  • imgii
  • html2text

Because curses is not included on Windows distributions of Python, Windows users may want to run tread in Cygwin (or maybe bash for Windows would work). Alternatively, you can make a go of it with one of the several curses implementations available for Windows.

Basic Usage

Once installed, run tread.


By default, tread assumes that your configuration file is located at ~/.tread.yml. If it isn't, you may specify a configuration file at runtime: tread config.yml.

If the configuration file can't found at runtime, tread will create a configuration file for you with reasonable defaults and copy it to the specified (or default) location. You may then edit this file to add feeds or change optional parameters.

Subscribing to a Feed

While some optional parameters can be configured (who doesn't love tweaking HTTP request timeout values?), most users will primarily use the configuration file to specify the feeds to which they want to subscribe. For each feed, tread requires a name and a url, in the following format:

  - name: Bad Astronomy
  - name: Whatever
  - name: Waypoint
  - name: Motherboard
  - name:
  - name: xkcd

Make sure that you get the spacing right (using spaces, not tabs); YAML can be a little finicky.

Supported Parsers

Several parsers are available to convert the HTML content found in RSS feeds to text easily displayed in a terminal. The parser to use is specified using the configuration file's parser field.

Acceptable values for the parser field are: html2text (default), lynx, and w3m.

If you'd prefer to avoid external calls, you probably want to use html2text, which will convert the content to markdown; the lynx and w3m browsers can also be used to parse the content (if you have them installed).

Updating Feeds

Your feeds will be updated periodically while you use tread, and you can manually update a feed by hitting the key dfined in your configuration YAML file (which defaults to U).

If you want to keep your feeds up-to-date even when the program isn't open you can use cron (or something similar) to schedule updates. This is helpful if you subscribe to a site that posts a lot of content (or has a short RSS history) and you don't check your feed reader every day.

To update your feeds in a non-interactive mode, simply pass the --update (or -u) flag:

$ tread --update

If you want your feeds to be updated daily at 09:00, add the following line to your crontab with crontab -e:

0 9 * * * tread --update

On OS X, there are plenty of apps available for scheduling tasks; if you don't want to install a new application, you can use the builtin launchd, although it can be a little more complicated.

Bugs and Feature Requests

Feature Requests

  • Support for ATOM feeds
  • Allow feed URLs to be updated (e.g., maybe with "previous_url" in YAML?)
  • View toggles to display only unread or only starred items (or the combination of those two)
  • Ability to scroll feed list
  • Configurable DB pruning (only keep X days to prevent DB from ballooning)
  • Colour support for images
  • bcj recommends changing the name to cuRSSes

Known Bugs

  • When an image is displayed in a feed item and a series resizes occur, way too many external requests get generated, and hosts will frequently stop responding (and it's slow); solve by caching all ASCII images in a dict by URL
  • Resizing the screen results in losing the contents of the messages window (oh well)
  • Currently ignores the <sy:updatePeriod>, <sy:updateFrequency>, and <sy:updateBase> tags in favour of re-fetching each feed at the interval specified in the config file

License Information

Written by Gem Newman. Website | GitHub | Twitter

This work is licensed under Creative Commons BY-SA 4.0.

Remember: GitHub is not my CV.


A very simple terminal RSS feed reader.







No packages published