← Back to home


Allthough I’ve riced newsboat, this will be a guide focusing on the important aspect of the program. Newsboat allows the user to read RSS/Atom feeds, which are usually generated by the website itself or sometimes by a frontend or third party app. The main reason to use this program is the fact that you won’t need an account in sites such as Youtube, Reddit, or Twitter anymore. Also, that you’ll have sort of a centralized way to consume (which includes reading text, listening to podcasts or watching videos) pretty much any site on the internet by using only a terminal program, which is by far faster and more desirable. This guide includes:

  • Brief explanation on how it works (program is very intuitive to use)
  • Setup of other programs
  • Running newsboat in the background so it notifies the user when new article appears (optional)
  • Multiple macro configurations that you might find very useful (optional but HIGHLY recommended)


The software is at almost any repository. In case it is not on your distro, you can always build it from source.

For Arch-based systems:

pacman -S newsboat mpv

I use firefox for opening up links (unless is the article has only text) and mpv to reproduce videos and audios. You can use any other browser and media player obviously. Or, you can use something like w3m to read text, but remember to change it as the browser when setting up the program.

Also, if you want to download videos/audios I recommend installing yt-dlp from its github’s repository. The installation is straightforward and the software is easier to update by using yt-dlp -U once needed. This program is a fork of the discontinued youtube-dl which may still appear in some distro’s repositories.



Newsboat won’t run unless the file urls has something inside. Both config and urls files are at either $HOME/.newsboat or $XDG_CONFIG_HOME/newsboat. Put something inside the urls file. I recommend using the following frontends for getting the feeds:

  • Twitter -> nitter
  • Youtube -> Invidious
  • Reddit -> teddit

Say you want to add the youtube channel HydeWars to your feed. It will look like this:


So basically, you need to get the channel’s ID which is UCfUaZ8Ra7m7BqUEACv2jySw and add it at the end of the url, where vid.puffyan.us is an instance of Invidious. How you find the ID of a YT channel is a matter of having at least a 2 digits IQ. If you don’t want to use an Invidious instance, you can go to any Youtube channel and view the souce code, filter keyword rss and see how the URL looks.

You can also tag URLs and then press t by adding the tag at the end of the string after a blank space:

https://vid.puffyan.us/feed/channel/UCfUaZ8Ra7m7BqUEACv2jySw MDE

Now open config file and add:

reload-time 30 
auto-reload yes
browser "setsid -f $BROWSER --new-tab %u > /dev/null 2>&1"
cleanup-on-quit yes
history-limit 2000
show-keymap-hint no
goto-next-feed no
error-log ".config/newsboat/error.log"
prepopulate-query-feeds yes
suppress-first-reload yes

notify-always no 
notify-program "/usr/bin/dunstify"
notify-format "Newsboat: %d new articles"

Line 4 sets up the browser and forks it, while opening the url in a new tab. In my case, I have an env var set to firefox. Change $BROWSER to your browser’s name or software for reading text, if you need to. Then, for notifications I use dunstify but you can use whatever you like. Rest is self explanatory, but keep in mind that if you are going to setup notifications you should keep reload-time and auto-reload as they are.

Optionally, you can set up vim-like bindings:

# Vim keybindings
unbind-key j
unbind-key k
unbind-key ENTER
unbind-key o 

bind-key o open 
bind-key k up
bind-key j down


Open $XDG_CONFIG_HOME/mpv/mpv.conf and add:

# Cache

# Quality stream

# Yt-dlp hook

This sets up a yt-dlp hook that will make the streaming faster. Also, if you want higher/lesser quality, change the height value.


I recommend you to set up a download folder. Open up $XDG_CONFIG_HOME/yt-dlp/config and add:

-o '/path/to/folder/%(title)s.%(ext)s'

This will save the video/audio to a folder using metadata.

Running newsboat through a script for notifications

Instead of running newsboat directly, I use a simple script so it is always on the background. You can also achieve this with cronjobs.


while true; do
    kill $(pidof newsboat)
    rm $XDG_CONFIG_HOME/newsboat/queue
    $TERMINAL -e newsboat
    if [[ $? == 0 ]] ; then
        exec newsboat && break

chmod +x the script and remember to use it instead of directly executing newsboat. In my case, I use an i3’s keybinding for quick access, and also for executing the script only one time as soon as the window manager initializes.


A macro is used for executing a sequence of commands by pressing a key or a combination of keys. In our case, for using the browser setting as not really a browser, but anything we like. For example, as a media player to reproduce a YT video. To execute a macro press , + key.

Here is a list of some macros I’ve came up with that are very useful (add them to newsboat’s config file):

Queue videos, clear playlist and reproduce playlist

macro a set browser "echo %u >> ~/.config/newsboat/queue" ; open-in-browser ; set browser "$BROWSER %u"
macro c set browser "rm $HOME/.config/newsboat/queue > /dev/null 2>&1" ; open-in-browser ; set browser "$BROWSER %u"
macro p set browser "kill $(pidof mpv) ; setsid -f mpv --playlist=$HOME/.config/newsboat/queue > /dev/null 2>&1" ; open-in-browser ; set browser "$BROWSER %u"

The idea of these 3 macros is creating, playing or deleting a playlist. If you take a look at the script in the previous section, this file named queue gets deleted when the script executes. For adding videos or even audios to said file you need to focus the article on a feed.

Play queued videos fullscreen second monitor

macro P set browser "kill $(pidof mpv) ; setsid -f mpv --x11-name=newsboatfs --fullscreen=yes --playlist=$HOME/.config/newsboat/queue > /dev/null 2>&1" ; open-in-browser ; set browser "$BROWSER %u"

Play video

macro v set browser "kill $(pidof mpv) ; setsid -f mpv %u > /dev/null 2>&1" ; open-in-browser-and-mark-read ; set browser "$BROWSER %u" 

Play video floating mode

macro i set browser "kill $(pidof mpv) ; setsid -f mpv --x11-name=mpvfloat %u > /dev/null 2>&1" ; open-in-browser-and-mark-read ; set browser "$BROWSER %u"

Play audio only

macro A set browser "kill $(pidof mpv) ; setsid -f mpv %u --no-video > /dev/null 2>&1" ; open-in-browser-and-mark-read ; set browser "$BROWSER %u" 

Play fullscreen, i3 sends it to second monitor (useful for playing all the videos from a channel)

macro f set browser "kill $(pidof mpv) ; setsid -f mpv --x11-name=newsboatfs --fullscreen=yes %u > /dev/null 2>&1" ; open-in-browser ; set browser "$BROWSER %u"

Download video

macro y set browser "yt-dlp %u" ; open-in-browser ; set browser "$BROWSER %u"

Open in default browser

macro o open-in-browser

NOTE: Keep in mind that for sending the videos/articles to another monitor you need to rename the X instance to whatever you like so you can then manipulate it with your window manager. Using i3 would look like this:

for_window [instance="newsboatfs"] move container to workspace $ws10
for_window [instance="mpvfloat"] floating enable, resize set 960 540, move container position center 

Where $ws10 outputs to HDMI-1:

workspace "10" output HDMI-1

Use xrandr to know display names.