Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

A terminal feed reader.

Project Description

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: Boing Boing
- name: Whatever
- 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

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
* 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
* Looks like some Unicode characters aren't working right, such as the title
text in this xkcd comic:
* Resizing the screen results in losing the contents of the messages window (oh
* 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](
Release History

Release History

This version
History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
tread-0.9.3.tar.gz (16.8 kB) Copy SHA256 Checksum SHA256 Source Nov 23, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting