NewsBlur is a personal news reader bringing people together to talk about the world.



Get it on F-Droid Get it on Google Play


  1. Shows the original site (you have to see it to believe it).
  2. Hides stories you don't want to read based on tags, keywords, authors, etc.
  3. Highlights stories you want to read, based on the same criteria.



  • Python 2.7+: The language of choice.
  • Django: Web framework written in Python, used to serve all pages.
  • Celery & RabbitMQ: Asynchronous queueing server, used to fetch and parse RSS feeds.
  • MongoDB, Pymongo, & Mongoengine: Non-relational database, used to store stories, read stories, feed/page fetch histories, and proxied sites.
  • PostgreSQL: Relational database, used to store feeds, subscriptions, and user accounts.
  • Redis: Programmer's database, used to assemble stories for the river, store story ids, manage feed fetching schedules, and the minuscule bit of caching that NewsBlur uses.
  • Elasticsearch: Search database, use for searching stories. Optional.

Client-side and design

  • jQuery: Cross-browser compliant JavaScript code. IE works without effort.
  • Underscore.js: Functional programming for JavaScript. Indispensable.
  • Backbone.js: Framework for the web app. Also indispensable.
  • Miscellaneous jQuery Plugins: Everything from resizable layouts, to progress bars, sortables, date handling, colors, corners, JSON, animations. See the complete list.

Installation Instructions


What you can safely ignore

Not every program listed in the Prerequisites section is necessary to run NewsBlur.

  • Elasticsearch is the only module that requires Java. If you can live without searching for feeds or searching for stories, then you can ignore it and NewsBlur will just spit out that you don't have a search server in the logs.
  • Jammit is for asset compression. Don't bother using it since the alternative is to just serve every js and css file in individual files without compression. Besides, nginx gzips those files automatically if you use the built-in nginx config. Just set DEBUG_ASSETS = True in your (which is also in
  • numpy and scipy are used for the colors used all over the site. Every site's favicon is analyzed for its dominant color, and that color is what gives every site its feel. You'll see it by every story all over. I'd recommend installing it, as you can just use prebuilt packages and don't have to install from source, which is possible but not trivial.

Relational Database (MySQL, PostgreSQL)

You will want to have your database set up before you begin installation. Fabric can install both PostgreSQL and MongoDB for you, but only on Ubuntu. Mac OS X users will want to have MySQL or PostgreSQL already installed. You can download MySQL or download PostgreSQL. Additionally, if running as a development machine on Mac OS X, I would recommend using MySQL with Sequel Pro as a GUI.

If you are installing MySQL, you will also need the MySQLDB python library:

sudo easy_install mysql-python


Both Mac OS X and Linux require Fabric to be installed. Many common tasks, such as installing dependencies, deploying servers, migrations, and configurations are in

sudo easy_install fabric

On recent installations of Mac OS X using XCode 4, you may run into issues around the ppc architecture. To fix this, simply run:

sudo ln -s /Developer/Platforms/iPhoneOS.platform/Developer/usr/libexec/gcc/darwin/ppc \
sudo ln -s /Developer/Platforms/iPhoneOS.platform/Developer/usr/libexec/gcc/darwin/ppc \

Sym-linking the ppc architecture comes from this StackOverflow answer on "assembler for architecture ppc not installed on Mac OS".


On top of MySQL/PostgreSQL, NewsBlur uses MongoDB to store non-relational data. You will want to download MongoDB. If you are on Ubuntu, the setup_mongo Fabric command will automatically do this for you, but Mac OS X needs to have it installed manually.

Numpy and Scipy

Not the easiest to get installed. If you are running Mac OS X, you have a few options:


You must have Java 7 installed to run Jammit.

Other assorted packages

From inside the repository, run:

pip install -r requirements.txt

Configure paths

In there are two paths that need to be configured.

  • env.paths.NEWSBLUR is the relative path to the NewsBlur repository.
  • env.paths.VENDOR is the relative path to where all downloaded code should go.

In there are a few paths that need to be configured. Configure these after the installation below.

Installing on Mac OS X

  1. Using Mac OS X as a development environment, you can run all three servers (app, db, task) on the same system. You should have Fabric installed to run the You should also have MySQL/PostgreSQL and MongoDB already installed.

    fab -R local setup_python
    fab -R local setup_mongoengine
    fab -R local setup_forked_mongoengine
    fab -R local setup_repo_local_settings
    fab -R local compress_assets

    If any of the packages fail to install (lxml, for instance), look through and check if there is a function that can be used to circumvent broken easy_install processes. For example, lxml may need libxslt and libxml2 to be installed. This is automated with the following Fabric command:

    fab -R local setup_libxml_code
  2. Configure MySQL/PostgreSQL by adding in a newsblur user and a newsblur database. Here's an example for MySQL:

    mysql_install_db --verbose --user=`whoami` --basedir="$(brew --prefix mysql)" --datadir=/path/to/var/mysql --tmpdir=/tmp
    mysql.server start
    mysql -u root
    > CREATE USER 'newsblur'@'localhost' IDENTIFIED BY '';
    > GRANT ALL PRIVILEGES ON *.* TO 'newsblur'@'localhost' WITH GRANT OPTION;
    > CREATE DATABASE newsblur;
    > exit

    Then load up the database with empty NewsBlur tables and bootstrap the database:

    ./ syncdb --all --noinput
    ./ migrate --fake
    ./ migrate
    ./ loaddata config/fixtures/bootstrap.json
  3. Start mongodb (if not already running):

    mongod run
  4. Run the development server. At this point, all dependencies should be installed and no additional configuration is needed. If you find that something is not working at this point, please email the resulting output to Samuel Clay at [email protected].

    ./ runserver
  5. Navigate to:


    Create an account. At the end of the account creation process, you will be redirected to https://localhost/profile/stripe_form. Hit the back button a few times, and you will be inside the app.

Installing on Linux / Ubuntu

If you are on Ubuntu, you can simply use Fabric to install NewsBlur and its many components. NewsBlur is designed to run on three separate servers: an app server, a db server, and assorted task servers. To install everything on a single machine, read through and setup all three servers (app, db, and task) without repeating the setup_common steps.

Finishing Installation

You must perform a few tasks to tie all of the various systems together.

  1. First, copy and fill in your OAuth keys, S3 keys, database names (if not newsblur), task server/broker address (RabbitMQ), and paths:


    Edit to change any keys that you have.

  2. Create the newsblur database in MySQL/PostgreSQL


    ./ migrate

App server

fab -R local setup_app

Database server

fab -R local setup_db

Task server

fab -R local setup_task

Keeping NewsBlur Running

These commands keep NewsBlur fresh and updated. While on a development server, these commands do not need to be run more than once. However, you will probably want to run the refresh_feeds command regularly so you have new stories to test with and read.

Fetching feeds

If you just want to fetch feeds once, you can use the refresh_feeds management command:

./ refresh_feeds

If you want to fetch feeds regardless of when they were last updated:

./ refresh_feeds --force

You can also fetch the feeds for a specific user:

./ refresh_feeds --user=newsblur

You'll want to put this refresh_feeds command on a timer to keep your feeds up to date.


To populate the feedback table on the homepage, use the collect_feedback management command every few minutes:

./ collect_feedback


To populate the statistics graphs on the homepage, use the collect_stats management command every few minutes:

./ collect_stats

Bootstrapping Search

Once you have an elasticsearch server running, you'll want to bootstrap it with feed and story indexes.

./ index_feeds

Stories will be indexed automatically.

If you need to move search servers and want to just delete everything in the search database, you need to reset the MUserSearch table.

>>> from import MUserSearch
>>> MUserSearch.remove_all()

Running unit and integration tests

NewsBlur comes complete with a test suite that tests the functionality of the rss_feeds, reader, and feed importer. To run the test suite:

./ test --settings=utils.test_settings

In Case of Downtime

You got the downtime message either through email or SMS. This is the order of operations for determining what's wrong.

0a. If downtime goes over 5 minutes, go to Twitter and say you're handling it. Be transparent about what it is, NewsBlur's followers are largely technical. Also the 502 page points users to Twitter for status updates.

0b. Ensure you have secrets-newsblur/configs/hosts installed in your /etc/hosts so server hostnames work.

  1. Check to confirm it's down.

    If you don't get a 502 page, then NewsBlur isn't even reachable and you just need to contact the hosting provider and yell at them.

  2. Check which servers can't be reached on HAProxy stats page. Basic auth can be found in secrets/configs/haproxy.conf. Search the secrets repo for "gimmiestats".

    Typically it'll be mongo, but any of the redis or postgres servers can be unreachable due to acts of god. Otherwise, a frequent cause is lack of disk space. There are monitors on every DB server watching for disk space, emailing me when they're running low, but it still happens.

  3. Check Sentry and see if the answer is at the top of the list.

    This will show if a database (redis, mongo, postgres) can't be found.

  4. Check the various databases:

    a. If Redis server (db_redis, db_redis_story, db_redis_pubsub) can't connect, redis is probably down.

    SSH into the offending server (or just check both the `db_redis` and `db_redis_story` servers) and
    check if `redis` is running. You can often `tail -f -n 100 /var/log/redis.log` to find out if
    background saving was being SIG(TERM|INT)'ed. When redis goes down, it's always because it's
    consuming too much memory. That shouldn't happen, so check the [munin
    Boot it with `sudo /etc/init.d/redis start`.

    b. If mongo (db_mongo) can't connect, mongo is probably down.

    This is rare and usually signifies hardware failure. SSH into `db_mongo` and check logs with `tail
    -f -n 100 /var/log/mongodb/mongodb.log`. Start mongo with `sudo /etc/init.d/mongodb start` then
    promote the next largest mongodb server. You want to then promote one of the secondaries to
    primary, kill the offending primary machine, and rebuild it (preferably at a higher size). I
    recommend waiting a day to rebuild it so that you get a different machine. Don't forget to lodge a
    support ticket with the hosting provider so they know to check the machine.
    If it's the db_mongo_analytics machine, there is no backup nor secondaries of the data (because
    it's ephemeral and used for, you guessed it, analytics). You can easily provision a new mongodb
    server and point to that machine.
    If mongo is out of space, which happens, the servers need to be re-synced every 2-3 months to 
    compress the data bloat. Simply `rm -fr /var/lib/mongodb/*` and re-start Mongo. It will re-sync.
    If both secondaries are down, then the primary Mongo will go down. You'll need a secondary mongo
    in the sync state at the very least before the primary will accept reads. It shouldn't take long to
    get into that state, but you'll need a mongodb machine setup. You can immediately reuse the 
    non-working secondary if disk space is the only issue.

    c. If postgresql (db_pgsql) can't connect, postgres is probably down.

    This is the rarest of the rare and has in fact never happened. Machine failure. If you can salvage
    the db data, move it to another machine. Worst case you have nightly backups in S3. The
    has commands to assist in restoring from backup (the backup file just needs to be local).
  5. Point to a new/different machine

    a. Confirm the IP address of the new machine with fab list_do.

    b. Change secrets-newsbur/config/hosts to reflect the new machine.

    c. Copy the new hosts file to all machines with:

    fab all setup_hosts

    d. Changes should be instant, but you can also bounce every machine with:

    fab web deploy
    fab task celery

    e. Monitor utils/ and utils/ for lots of reading and feed fetching.

  6. If feeds aren't fetching, check that the tasked_feeds queue is empty. You can drain it by running:


This happens when a deploy on the task servers hits faults and the task servers lose their 
connection without giving the tasked feeds back to the queue. Feeds that fall through this 
crack are automatically fixed after 24 hours, but if many feeds fall through due to a bad 
deploy or electrical failure, you'll want to accelerate that check by just draining the 
tasked feeds pool, adding those feeds back into the queue. This command is idempotent.



NewsBlur is licensed under the MIT License. (See LICENSE)

  • iOS: dark mode

    iOS: dark mode

    Every app that someone might read in bed needs a dark mode. We should add this (I know of many people who won't use an app without such a feature, like CGP Grey).

    All views should be updated to support the option of a black background with light text, in addition to the current colors.

    For stories especially, it'd be good to support four background colors, like the Safari view controller: white, sepia, gray & black.

    It'd be good to have a preference to automatically switch based on the brightness of the screen, in addition to a preference for the background color.

    A two-finger vertical swipe to manually switch would also be a nice feature (like in Tweetbot etc).

    medium iOS 
    opened by Dejal 51
  • Android: Address lag on version 4.0

    Android: Address lag on version 4.0

    Looks like many people are complaining about lag. When most reinstall the app, everything's better. What can we do about this? I want an update about ASAP to either wipe the DB and make things fast or figure out where the lag is coming from.

    critical android 
    opened by samuelclay 42
  • Web: 'v'/'o' no longer open stories in background

    Web: 'v'/'o' no longer open stories in background

    Chrome 41.0.2272.16 beta (64-bit) OS X Mavericks 10.9.5

    Preference Stories > Open Links > In New Tab is selected. Using 'Feed' view and 'Full' mode (not 'List').

    Focusing a story via 'j'/'k' and then pressing 'o' opens the story in a foreground tab. The expected behavior is for it to open in a background tab.

    I'm assuming Chrome just updated because it was definitely working last weekend and other than possibly Newsblur that's the only thing that could be different.

    I'm not seeing any errors or warnings in the Console, so I'm guessing Google changed the handling of MouseEvents. In looking at the open_story_in_new_tab function within NewsBlur/media/js/newsblur/models/stories.js I notice it uses init_mouse_events which MDN says is deprecated. I'm not well versed in JS and my attempt at changing that (and the previous line) to b = new MouseEvent("click", {bubbles: true, cancelable: true, view: window, ctrl:true, meta:true}); in Chrome's dev tools only made it open the link in the current tab instead.

    This was also noted by another user on GetSatisfaction.

    opened by TheQwerty 36
  • Please separate personal preferences from the install

    Please separate personal preferences from the install

    I tried installing a local version to tryout NewsBlur only to find that without warning the installer changes my default shell to zsh. There's also nothing indicating it's going to setup a firewall. I recommend moving this kind of stuff into something like "provision_extras" that can be run first for your servers, but I wouldn't need to run.

    I tried using setup_all, which looks like how I could run it on just one box locally.

    I'm also a developer, I understand this is an extremely low priority. If I try the install again I'll make these changes and send a pull request if you haven't got to it first.

    opened by AsaAyers 35
  • iOS: widget for iOS 14

    iOS: widget for iOS 14

    WWDC20 has deprecated the current widget mechanism, in favor of a SwiftUI-based non-interactive design.

    The current implementation is still supported for now, but is limited to the bottom of the Today view instead of the home screen on iOS 14, and will probably stop working in due course. The widget will need to be rewritten using SwiftUI.

    For NewsBlur, this shouldn't be too problematic, since it displays stories, and tapping one opens the app. It should be feasible to reimplement that using WidgetKit. Probably not urgent; won't be able to have the widget on a home screen until this is done, but the new widget wouldn't work on iOS 13 and earlier.

    high iOS 
    opened by Dejal 34
  • Android: Interactions and Activities view

    Android: Interactions and Activities view

    Just like iOS and web.

    screen shot 2015-05-21 at may 21 10 56 02 am screen shot 2015-05-21 at may 21 10 58 04 am

    On iOS:

    img_2798 2 img_2800 2

    Note that I have a couple bugs to fix on iOS. It should strip HTML on interactions, and it should be loading those icons in Activity.

    medium android android-feed-list 
    opened by samuelclay 31
  • Android: Hide action bar and soft menu/back buttons when reading in story view

    Android: Hide action bar and soft menu/back buttons when reading in story view

    In the Pocket Android app when you are reading the story the action bar and menu/back buttons automatically hide when you start scrolling down. This maximises the screen space for the text. When you reach the end or start scrolling up they reappear.

    I think it would be nice to do this in the story view.

    android android-story-detail 
    opened by manderson23 28
  • iOS: three column layout on iPad

    iOS: three column layout on iPad

    Idea: the web app has a three-column layout (feeds, detail, story). This could be done in the iPad app too, perhaps with a narrow column on the left side, just wide enough for icons, which expands to show the full width when tapped, perhaps via a slide-over animation, or making the second column narrower till an item is tapped.

    On iPad Pro, there's enough room for full width of all three columns.

    high iOS 
    opened by Dejal 27
  • Backend: Many Common Embeds Broken

    Backend: Many Common Embeds Broken

    Since many types of media embed (twitter, instagram, flickr, imgur, etc) have switched to using a specially-named DIV that triggers some javascript to load the actual content, many stories that consist mostly of these embeds (for example, a blog post about a series of tweets) show up and uselessly empty. It seems that many RSS feeds strip out the required script tags for some reason, breaking the original content. It would be fairly cheap/easy to re-enhance the story HTML with these missing tags if we see any of the well-known DIV names and fix the broken content and would really save our users the time and headache of leaving the app and having to load a whole web page.

    backend high 
    opened by dosiecki 23
  • Android: Story notifications

    Android: Story notifications

    This is a big ticket feature. There are two parts to this feature, this ticket only focuses on the actual notification. Choosing notifications for feeds is the next ticket, but we can launch that later.

    1. Go on the web and right-click feeds to setup "Notifications" for android. You should be able to see it as it's available to admins.

    2. After /reader/feeds?flat=true is loaded, loop through every feed and check if 'android' is in any feed.notification_types. If so, request notification privileges on the device.

    3. Once android gives you a notification token that can be used for pushing remote notifications, send that token to POST to /notifications/android_token/ with android_token as the key. This is idempotent, so you can submit this over and over again with the same token. That's what we do on iOS, to handle changing tokens. This endpoint is also device-aware, so multiple devices can submit different tokens to the same endpoint and each device will receive notifications.

    Use to test notifications. Feel free to hit it as much as you like.

    Ideally I'd like to get images in the notification preview, as I did on iOS.

    photo nov 21 5 15 53 pm photo nov 21 5 16 14 pm photo nov 21 5 16 17 pm

    high android 
    opened by samuelclay 22
  • Android: Mark previous as read has issues where feed contains multiple items with same timestamp

    Android: Mark previous as read has issues where feed contains multiple items with same timestamp

    The hacker news feed contains multiple items with the same timestamp. When I mark previous as read in folder view (unread/oldest) on a story that isn't the last with that timestamp all stories with that timestamp are marked as read.

    Need to confirm whether this is also an issue in feed view.

    opened by manderson23 21
  • fixes issues with subdomain hosting of user blurblogs

    fixes issues with subdomain hosting of user blurblogs

    This is a super simple fix for the problem I outlined in this forum post. Instead of looking at the current host and checking to see if there is exactly 2 periods.. I am saying if there are 2 or more then just return the first split is presumed to be the sub (maybe sub sub) domain that we care about.

    It works for me with the NewsBlur being served at, but I could imagine this working with even more nested sub domains.. ¯_(ツ)_/¯

    opened by usmcamp0811 0
  • Option for email other than mailgun

    Option for email other than mailgun

    Maybe I'm blind or something, but it seems like there's no option for a free-tier anymore with Mailgun. Are there any alternatives I can use instead that the system supports? I couldn't seem to find anything from the documentation that exists.

    Apologies if I missed it.

    opened by Berzerker 0
  • git-web rss feed doesn't work

    git-web rss feed doesn't work

    heya i just discovered git-web and would like to add a repository's rss feed to my newsblur, but i'm getting the error: This address does not point to an RSS feed or a website with an RSS feed. despite the url appearing to point to an rss feed.. is this perhaps because it uses standard browser authentication asking for a username and password?

    opened by luxiouronimo 4
  • is it safe to prune docker images?

    is it safe to prune docker images?

    it seems i've been running newsblur docker for almost 2 years; while doing some system maintenance i saw several 'Unused' and 'Unused (dangling)' docker images..

    i also discovered the docker system prune -a command, and wonder if it's safe to run, or if there's some method of clearing out the old stuff..

    opened by luxiouronimo 0
  • web: rogue rss feed

    web: rogue rss feed

    Check this feed: It works fine under android client. But selecting it under web interface confuses browser and page is shown instead of newsblur web-ui.

    opened by Peter774 0
Samuel Clay
Founder of NewsBlur and Turn Touch
Samuel Clay
Team Curie is a group of people working together to achieve a common aim

Team Curie is a group of people working together to achieve a common aim. We are enthusiasts!.... We are setting the pace!.... We offer encouragement and motivation....And we believe TeamWork makes the DreamWork.

null 4 Aug 7, 2021
Personal Finance Forecaster - An AI tool for forecasting personal expenses

Personal Finance Forecaster - An AI tool for forecasting personal expenses

null 2 Mar 9, 2022
This library is an ongoing effort towards bringing the data exchanging ability between Java/Scala and Python

PyJava This library is an ongoing effort towards bringing the data exchanging ability between Java/Scala and Python

Byzer 6 Oct 17, 2022
Demo repository for Saltconf21 talk - Testing strategies for Salt states

Saltconf21 testing strategies Demonstration repository for my Saltconf21 talk "Strategies for testing Salt states" Talk recording Slides and demos Get

Barney Sowood 3 Mar 31, 2022
Make dbt docs and Apache Superset talk to one another

dbt-superset-lineage Make dbt docs and Apache Superset talk to one another Why do I need something like this? Odds are rather high that you use dbt to

Slido 81 Jan 6, 2023
A redesign of our previous Python World Cup, aiming to simulate the 2022 World Cup all the way from the qualifiers

A redesign of our previous Python World Cup, aiming to simulate the 2022 World Cup all the way from the qualifiers. This new version is designed to be more compact and more efficient and will reflect the improvements in our programming ability.

Sam Counsell 1 Jan 7, 2022
Comics/doujinshi reader application. Web-based, will work on desktop and tablet devices with swipe interface.

Yomiko Comics/doujinshi reader application. Web-based, will work on desktop and tablet devices with swipe interface. Scans one or more directories of

Kyubi Systems 26 Aug 10, 2022
An easy FASTA object handler, reader, writer and translator for small to medium size projects without dependencies.

miniFASTA An easy FASTA object handler, reader, writer and translator for small to medium size projects without dependencies. Installation Using pip /

Jules Kreuer 3 Jun 30, 2022
Tie together `drf-spectacular` and `djangorestframework-dataclasses` for easy-to-use apis and openapi schemas.

Speccify Tie together drf-spectacular and djangorestframework-dataclasses for easy-to-use apis and openapi schemas. Usage @dataclass class MyQ

Lyst 4 Sep 26, 2022
An OBS script to fuze files together

OBS TEXT FUZE Fuze text files and inject the output into a text source. The Index file directory should be a list of file directorys for the text file

SuperZooper3 1 Dec 27, 2021
Secret santa is a fun and easy way to get together with your friends and/or family with a gift for them.

Secret Santa What is Secret Santa? Secret santa is a fun and easy way to get together with your friends and/or family with a gift for them. The idea i

null 2 Dec 6, 2021
Table (Finnish Taulukko) glued together to transform into hands-free living.

taulukko Table (Finnish Taulukko) glued together to transform into hands-free living. Installation Preferred way to install is as usual (for testing o

Stefan Hagen 2 Dec 14, 2022
It is a personal assistant chatbot, capable to perform many tasks same as Google Assistant plus more extra features...

PersonalAssistant It is an Personal Assistant, capable to perform many tasks with some unique features, that you haven'e seen yet.... Features / Tasks

Roshan Kumar 95 Dec 21, 2022
personal dotfiles for rolling release linux distros

dotfiles Screenshots: Directions: Deploy my dotfiles with yadm Packages from arch listed in .installed-packages Information on osu! see ~/Games/osu!/.

-pacer- 0 Sep 18, 2022
Personal Assistant Tessa

Personal Assistant Tessa Introducing our all new personal assistant Tessa..... An intelligent virtual assistant (IVA) or intelligent personal assistan

Anusha Joseph 4 Mar 8, 2022
Generate your personal 8-bit avatars using Cellular Automata, a mathematical model that simulates life, survival, and extinction

Try the interactive demo here ✨ ✨ Sprites-as-a-Service is an open-source web application that allows you to generate custom 8-bit sprites using Cellul

Lj Miranda 265 Dec 26, 2022
A python script made for personal use to monitor for sports card restocks on since they are sold out often

TargetProductMonitor A python script made for personal use to monitor for sports card resocks on since they are sold out often. When a rest

Bryan Lorden 2 Jul 31, 2022
Personal Chat Assistance

Python-Programming Personal Chat Assistance {% import "bootstrap/wtf.html" as wtf %} <title>EVT</title> <script src="

PRASH_SMVIT 2 Nov 14, 2021
Aides to reduce a cheat file with a personal selection of the cheats you want to use.

Retroarch Cheat File Reducer Description Aides to reduce a cheat file with a personal selection of the cheats you want to use. Instructions Copy a sel

null 1 Jan 9, 2022