Skip to main content

Decentralised, minimalist microblogging service for hackers.

Project description

Latest version released on PyPi Build status of the master branch Test coverage Chat on gitter Package license

twtxt is a decentralised, minimalist microblogging service for hackers.

So you want to get some thoughts out on the internet? In a convenient and slick way? While also following the gibberish of others? Instead of signing up at a closed and/or regulated microblogging platform, getting your status updates out with twtxt is as easy as putting them in a publicly accessible text file. The URL pointing to this file is your identity, your account. twtxt than can tracks those text files, like a feedreader, and build your unique timeline out of them, depending on which files you track. The format is simple, human readable, and goes well together with all those beloved UNIX command line utilities.


tl;dr: twtxt is a CLI tool, as well as a format specification for self-hosted flat file based microblogging.


  • A beautiful command-line interface thanks to click.
  • Asynchronous HTTP requests thanks to asyncio/aiohttp and Python 3.
  • Integrates well with existing tools (scp, cut, echo, date, etc.) and your shell.
  • Don’t like the official client? Tweet using echo -e "`date -Im`\tHello world!" >> twtxt.txt!


Release version:

  1. Make sure that you have at least Python 3.4.1 installed.
  2. You than can install this package simply via pip:
$ pip3 install twtxt

Tip: Instead of installing the package globally (as root), you may want to install this package locally by passing --user to pip, but you then have to make sure that you have included ~/.local/bin/ in your $PATH. Using pyvenv and running twtxt from within a virtualenv is of course also an option!

  1. Now run twtxt quickstart. :)

Development version:

  1. Clone the git repository:
$ git clone
  1. Install the package via pip in developer mode:
$ pip3 install -e twtxt/


twtxt features an excellent command-line interface thanks to click. Don’t hesitate to append --help or call commands without arguments to get information about all available commands, options and arguments.

Here are a few of the most common operations you may encounter when using twtxt:

Follow a source:

$ twtxt follow bob
✓ You’re now following bob.

List all sources you’re following:

$ twtxt following
➤ alice @
➤ bob @

Unfollow a source:

$ twtxt unfollow bob
✓ You’ve unfollowed bob.

Post a status update:

$ twtxt tweet "Hello, this is twtxt!"

View your timeline:

$ twtxt timeline

➤ bob (5 minutes ago):
This is my first "tweet". :)

➤ alice (2 hours ago):
I wonder if this is a thing?


twtxt uses a simple INI-like configuration file. It’s recommended to use twtxt quickstart to create it. On Linux twtxt checks ~/.config/twtxt/config for it’s configuration. Consult get_app_dir to find out the config directory for other operating systems.

Here’s an example conf file, showing every currently supported option:

nick = buckket
twtfile = ~/twtxt.txt
check_following = True
use_pager = False
limit_timeline = 20
post_tweet_hook = "scp {twtfile}"

bob =
alice =

[twtxt] section:

Option: Type: Default: Help:
nick TEXT   your nick, will be displayed in your timeline
twtfile PATH   path to your local twtxt file
check_following BOOL True try to resolve URLs when listing followings
use_pager BOOL False use a pager (less) to display your timeline
limit_timeline INT 20 limit amount of tweets shown in your timeline
post_tweet_hook TEXT   command to be executed after tweeting

post_tweet_hook is very useful if you want to push your twtxt file to a remote (web) server. Check the example above tho see how it’s used with scp.

[followings] section:

This section holds all your followings as nick, URL pairs. You can edit this section manually or use the follow/unfollow commands of twtxt for greater comfort.

Format specification

The central component of sharing information, i.e. status updates, with twtxt is a simple text file containing all the status updates of a single user. One status per line, each of which is equipped with an ISO 8601 date/time string followed by a TAB character (\t) to separate it from the actual text. A specific ordering of the statuses is not mandatory.

The file must be encoded with UTF-8, and must use LF (\n) as line separators.

A status should consist of up to 140 characters, longer status updates are technically possible but discouraged. twtxt will warn the user if a newly composed status update exceeds this limit, and it will also shorten incoming status updates by default. Also note that a status may not contain any control characters.

Take a look at this example file:

2016-02-04T13:30+01 You can really go crazy here! ┐(゚∀゚)┌
2016-02-01T11:00+01 This is just another example.
2015-12-12T12:00+01 Fiat lux!


twtxt is released under the MIT License. See the bundled LICENSE file for details.

Project details

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
twtxt-1.0.0.tar.gz (13.8 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page