Poca is a fast, multithreaded and highly customizable command line podcast client, written in Python 3. As of 1.0 all planned features have been implemented.


Poca allows both for options for each individual subscription and global defaults that apply to every subscription.

  • Maximum amount. Specify how many episodes the subscription should get before deleting old episodes to make room for new ones.
  • Override ID3/Vorbis metadata. If you want Savage Love to have Dan Savage in the artist field (rather than The Stranger), poca will automatically update the metadata upon download of each new episode. Set ‘genre’ to be overwritten by ‘Podcast’ as a default. Or have poca add track numbers to shows that have left them out.
  • Filter a feed. Only want news reports in the morning or on Wednesdays? Use criteria such as filename and title, or the hour, weekday or date of publishing to filter what you want from a feed.
  • Rename files automatically. Not all feeds have sensibly named media files. Specify a renaming template like date_title to know what you’re dealing with or to get alphabetical ordering to match chronology.
  • From the top. A latecomer to Serial or other audiobook style podcasts? Poca introduces a special mode that gets the oldest episodes first, rather than the latest. To move on to later episodes simply delete old ones and poca will fill up with the next in line.
  • Keeping track. Poca logs downloads and removals to a local file so you easily see what’s changed. Or configure it with an SMTP server and get notified when a feed stops working.
  • Manage your shows. by editing an easy-to-understand xml file. Or use the accompanying tool to add, delete, sort them, or get info about their publishing frequency, average episode length and more.

Poca also: has excellent unicode support for feeds, filenames and tags, gets cover images for feeds, has the ability to spoof user agents, can pause your subscriptions, deals intelligently with interruptions, updates moved feeds (HTTP 301) automatically, and more.

See the Configuration section of the wiki for more details on features.



All configuration is done in a single XML-format file. For cron job compatibility, Poca has a quiet mode in addition to normal and verbose.


You can install poca using only setuptools but pip is recommended. Find pip for your distro in your repositories (for debian/ubuntu its “python3-pip”)

To generate a package installable by pip, in the source root directory (the one with setup.py) do:

python3 ./setup.py sdist

And then install the generated package (using root privileges)

pip3 install ./dist/poca-[VERSION].tar.gz

Running poca on a fresh install (no configuration) will place a copy of the example configuration in ~/.poca. The included feeds are there for illustrative purposes. Edit the configuration file, try them out or use poca-subscribe delete to clear it out and start afresh.

To remove Poca – having installed it using pip – simply do:

pip3 uninstall poca


  • You will need Python 3 for setup and running the program
  • The following third-party modules are required: feedparser, lxml, mutagen, requests
  • Pip can install all of these using ‘pip3 install [name of module]’


  • Source code is on github. Poca is licensed under the GPL v3.
  • Documentation is on readthedocs
  • Notes on development on github


Version (1.0)

  • Added file renaming options (#18)
  • More consistent output in normal and verbose mode
  • audiosearch api removed again due to service closure (#87)
  • Bugfixes, quibbles and niggles aplenty

Version 0.9

  • ‘Artificial’ track numbers (issue #43)
  • Support for tagging with other formats than mp3: Ogg, opus, mp4, flac, … (issue #18)
  • Reintroduced support for id3v2.3
  • poca-subscribe search: Seach for shows with audiosearch’s api
  • ‘Preview’ feed in poca-subscribe’s add command (issue #55)
  • Multithreading support with option for concurrent downloads as well as concurrent updates (issue #45)
  • Subscription URLs are automatically updated when feeds move (HTTP status code 301)
  • New dependency: Using requests library for download due to downloading in threads (urllib says no)

Version 0.8

  • Greatly simplified configuration parsing with lxml (new dependency)
  • System defaults in case of missing or bad config and user set global subscription defaults, like setting max_number to 3 unless overridden on a sub-specific basis.
  • poca-subscribe is a new cli tool to manage subscriptions

Version 0.7

  • Log: Terse logging (skip writing about subscription if nothing has changed) (issue #32)
  • Email logging: A sensible email logging system (issue #26)
  • Style: Investigating Syntastic complaints (issue #39)
  • Bug fix: Hangs on feeds without entry size info (issue #40)
  • Bug fix: Crash on entries without enclosures (issue #41)
  • Style: Using named tuples for Outcome (https://pythontips.com/2015/06/06/why-should-you-use-namedtuple-instead-of-a-tuple/)

Version 0.6

  • Limit by number of files (issue #14)
  • Filter entries (issue #29)
  • From the top: Option to start podcast from the beginning (issue #28)
  • Cover.jpg: Download cover image from feed (issue #25)
  • Testing for unicode exceptions in feed treatment and mp3 metadata (issue #17)
  • max_mb has been deprecated in favour of max_number
  • Spoofed useragent introduced as fallback if urllib is denied

Version 0.5

  • Completed port to Python 3
  • Completely revised and simplified stream and log output
  • Mp3 tagging reimplemented
  • New download function with proper timeouts

Release 0.4

  • Reduced functionality port to Python3