Out of Pocket and into the Wallabag

LWN.net needs you!

Without subscribers, LWN would simply not exist. Please consider signing up for a subscription and helping to keep LWN publishing.

By Joe Brockmeier
May 30, 2025

Mozilla has decided to throw in the towel on Pocket, a social-bookmarking service that it acquired in 2017. This has left many users scrambling for a replacement for Pocket before its shutdown in July. One possible option is wallabag, a self-hostable, MIT-licensed project for saving web content for later reading. It can import saved data from services like Pocket, share content on the web, export to various formats, and more. Even better, it puts users in control of their data long-term.

About wallabag

Social bookmarking was first made popular by a service launched in 2003, called del.icio.us (later just "Delicious"), that allowed people to save, store, and share their web bookmarks online. It was followed by a handful of similar services, including Read It Later, which launched in 2008 and upped the ante a bit: it not only saved a page's title and URL, it stashed the content on its servers for later access (hence the name). Read It Later became Pocket in 2012.

In 2013, Google announced that it was killing off Google Reader, its RSS-feed-aggregator service. This alarmed Nicolas Lœuillet, who worried that the same thing might happen to Pocket. To ensure he had a home for his saved articles and data he began work on a project for self-hosting saved web content called "poche", which is French for "pocket". He renamed it to wallabag in 2014 following some trademark unpleasantness.

The project consists of a web application written using the Symfony PHP framework, as well as a number of client applications and browser extensions to save data to wallabag or fetch articles for reading. The ecosystem page on GitHub has a full list of applications provided by the project, as well as "unofficial" clients that are written by others.

Users should have little trouble finding clients to fit their needs on the desktop or a mobile device. The project has Firefox and Chrome extensions as well for saving pages directly from the browser. Folks who use unsupported web browsers can use the JavaScript bookmarklet for wallabag to save pages without using an extension. Wallabag has official Android and iOS clients which are open source, though the Android app is licensed under the GPLv3 rather than the MIT license. There are several e-reader clients for reading content that has been saved to wallabag, a GNOME application called Read It Later, a command-line client, and even an emacs client. If none of the existing clients quite meet one's needs, the wallabag API seems well-documented for those who would like to write their own client, and there are API wrappers in Go, Java, JavaScript, and Rust.

Wallabag server

The project has installation instructions for running wallabag on shared hosting (where one might not have root access) or on a dedicated server. The project supports MySQL/MariaDB, PostgreSQL, or SQLite as the backend database. There is also a container image for use with Docker, Podman, or other container managers. Users who do not want to mess with self-hosting, at least not right away, can opt for paid hosting from third-party providers, including wallabag.it which is run by Lœuillet.

For my testing, I chose to run the container image with Podman, with SQLite as the database using this command:

    $ podman run -p 8282:80 -e \       "SYMFONY__ENV__DOMAIN_NAME=http://localhost:8282" \       -v /home/user/wallabag/data:/var/www/wallabag/data:z \       -v /home/user/wallabag/images:/var/www/wallabag/web/assets/images:z \       wallabag/wallabag

This starts the container and forwards localhost port 8282 to port 80 in the container (-p 8282:80). The documentation for the wallabag container image unfortunately omits the port number from the environment variable that specifies the domain name for Symfony (-e "SYMFONY__ENV__DOMAIN_NAME=http://localhost"). If the container is started without that, it will mostly work, except wallabag will be missing its CSS—which is not great if one wants to use the web interface.

The -v options create persistent storage volumes for the container; users should replace /home/user with the appropriate path on their system. Note the :z suffix at the end of the path specification for the volume mounts. That tells Podman to set the correct SELinux labels for the directory. Without that, if SELinux is enabled, the container will not be able to write into those directories and the container will not start.

Configuring wallabag

Once started, the wallabag container uses "wallabag" as the default administrative username and password. The first order of business should be to change the username and password after logging in. Clicking the "My account" menu with the person icon at the top, right-hand side of the web interface will bring up the menu for managing wallabag. Go to "Users Management" to edit the username if desired. The password can be changed by going to "Config" and then "Password".

The first user created has full administrative privileges on the wallabag server, so it is a good idea to create a second user for day-to-day use. Additional users do not have administrative privileges, and wallabag has no way to add additional administrative users via the web interface. However, it is possible to bump up a user's privileges via console commands.

Wallabag's other server settings, such as public URL sharing and export formats, can be tweaked by going to the "Internal Settings" page from the menu. By default, all of the sharing services that wallabag supports—such as diaspora*, Shaarli, and Unmark, are turned on by default. Unfortunately, wallabag does not have a feature specifically to share via ActivityPub/Mastodon yet, though there has been a GitHub issue open on the topic since 2017.

Using wallabag

To get this out of the way early: yes, wallabag's web interface does have a dark (and light) theme. Users have the option of choosing one or the other, or having the theme automatically follow system settings. I found the light theme more pleasant and usable, but that's likely because I prefer light themes in general.

Once wallabag is set up, it's time to start adding bookmarks. In the web interface there is a plus (+) icon at the top of the page for adding new bookmarks: just click that and copy the URL to add as a bookmark. The navigation menu for existing bookmarks is on the left-hand side of the page. It has entries for unread articles, archived (read) articles, and so forth.

Wallabag has a tagging system for categorizing saved pages. Each page can have multiple tags, and wallabag allows users to browse saved pages by tag. Naturally, wallabag has search and filtering features to help users sort through their pile of bookmarked pages. Search and filter are located in the top toolbar; search is invoked with the ubiquitous magnifying glass icon, and the filter menu icon is the upside-down triangle. Pages can be filtered by status (read, unread, starred, or annotated), tags, language, domain name, creation date, and more.

It is much more convenient to save pages directly from one's web browser than to navigate to wallabag and copy the URL over manually, so most folks will want to set up the Firefox or Chrome extension right away. Wallabag requires more than a username and password pair to connect clients to the server, though: users have to create a client ID and client secret pair as well. This can be found from the menu item "API clients management".

Wallabag attempts to fetch content to cache it for later reading, but results can be mixed. As one might expect, sites that are more straightforward HTML are saved without much trouble. On the other hand, sites with complex layouts, or that are festooned with ads and JavaScript, tend to produce poor results. Wallabag can also run into problems fetching content if the page is not found, access is forbidden, or otherwise unavailable.

The fetch errors documentation explains how to enable debug logs and troubleshoot problems with incomplete or incorrect content. The project encourages users to create issues on GitHub if something is breaking the wallabag parser and the problem is reproducible.

Assuming that content has been fetched and saved correctly, wallabag not only allows reading the content in the web interface; it can be exported to EPUB, PDF, XML, JSON, CSV, and plain text. It's not entirely clear to me why one might want to save a page to CSV, but the feature is there for anyone who wants it.

Wallabag's web interface also has an annotation feature that allows highlighting text and adding notes to pages. It is nice to be able to add notes to saved content, but the feature is somewhat limited in that annotations are not exported when one saves to EPUB, PDF, etc. It would be ideal if users could export annotations with their content, and separately. For example, many e-reader applications let users save annotations or highlighted phrases separately—which can be quite useful when gathering content while writing an article or report.

Importing

Wallabag can import data from Chrome or Firefox bookmarks, as well as several social-bookmarking services including Instapaper, Omnivore, Pinboard, and Pocket. With bookmarks, it is as simple as exporting one's bookmark data from Firefox or finding the bookmarks file from Chrome (or Chromium) and then going to the Import page in Wallabag to upload the file. For some services, like Pocket, it may be necessary to create an API key to import data. Wallabag's import page (go to the "My account" menu and click "Import") has short instructions for each service that it supports, and more detailed instructions in its documentation. The project also has a script for importing data from the command line.

I tested imports from Firefox bookmarks, Pocket, Instapaper, and from another instance of wallabag. I have not been a heavy user of Pocket or Instapaper, so I only had about 300 saved pages between the services. Even so, it took wallabag a few minutes to complete the import. In its documentation, the project acknowledges that "imports can take ages", and it has developed an optional asynchronous tasks system that users can set up if a server is going to be handling large imports. That is probably overkill for single-user systems where importing data is likely to be a one-time or infrequent task.

Other than speed, the import process seems to work well enough. It would be better if users had the option to add a tag to the content to identify it as imported content. For example, it'd be nice to be able to add a "firefox" tag to pages imported from Firefox bookmarks. It does allow users to mark imported content as read when importing, but it is an all-or-nothing affair.

Project

The most recent release of the wallabag server was version 2.6.12, a minor update pushed out on April 10. The last major feature release was version 2.6.0, which came out in June 2023. The most active contributors in that time frame are Lœuillet, Yassine Guedidi, and Jeremy Benoist. The project does not have a security list for announcing security vulnerabilities—they are simply announced along with releases that fix vulnerabilities. The project's security policy on GitHub is just a notice asking for vulnerabilities to be sent to the general-purpose "[email protected]" email address.

Generally, the project seems to be mature and active enough to give users confidence that it will be around for the long haul. However, it is also more informally run than some might like. Right now, many of the standard governance questions are unanswered. For instance, the ownership of trademarks, the wallabag.org domain, the GitHub organization, its code repositories, is a bit fuzzy. Also, what might happen if project creator Lœuillet was suddenly out of the picture—whether the project has a "bus factor" larger than one, in other words—is unclear from the outside.

Since Lœuillet runs a for-pay hosted wallabag service, it would be reassuring if the project had a clear statement on the separation between the project and his product. I emailed Lœuillet to ask about those topics, and he replied that these were things that the project had not previously considered. He indicated that he would follow up "very soon" with a response, and I will update the article if that reply arrives after publication.

The project maintains a set of milestones for upcoming releases on GitHub. The 2.7.0 release has no due date, but it appears to be down to a handful of unresolved issues before it is ready for release. That release will remove MOBI export, which was deprecated in 2024. 2.7.0 will also add the ability to search annotations.

For many people, wallabag will be a suitable replacement for Pocket. It has most of the same features, though arranged differently and perhaps not as attractively, as Pocket. In fact, it surpasses Pocket in several ways such as allowing export to EPUB, PDF, and other formats, which is not something in Pocket's feature set. The fact that users can run their own server is, of course, also a major selling point over any offering that depends on the whims of a company or organization that can shut down the service at any time.

---