buku: a text-file bookmark manager with a SQLite brain and no cloud

What buku replaces, and for whom

The README frames the origin plainly: the author could not find a command-line solution with a private, portable, merge-able database plus GUI integration. That sentence describes the gap buku fills. Browser bookmark stores are per-profile, hard to grep, and tied to an account if sync is on. A plain text file of URLs has no titles, no tags, and no deduplication. buku sits between the two: a SQLite database with an indexed schema, reachable through a single command.

The audience is narrow and identifiable. If you already keep notes in plain text and search them with grep or ripgrep, buku is the same habit applied to links. It is also a reasonable fit for anyone who wants to import years of Firefox or Chrome bookmarks once and then stop thinking about browser profiles. The README lists auto-import for Firefox, Google Chrome, Chromium, Vivaldi, Vivaldi Beta (Internal), Brave, and MS Edge. That list is the practical boundary of who benefits: desktop browser users on Linux, macOS, or Windows, comfortable in a shell.

It is not for someone who wants a phone app. The topics list includes Termux, and the clipboard dependency table mentions termux-clipboard, but there is no mobile client. Nor is it a social or collaborative tool. There is no sharing model in the README, and the database is a local file.

How buku stores and searches bookmarks

The storage layer is SQLite, which is why portability works: the database is one file, and the README calls it merge-able, meaning you can sync it between systems rather than export and re-import. Python 3.10 or newer is required, per both the dependency table and the requires-python field in pyproject.toml. There is no server process in the CLI path.

Metadata comes from two places. You supply tags and comments; buku fetches the title and description from the page when you add a URL. That fetch depends on urllib3 and certifi for HTTPS and on beautifulsoup4 and html5lib for parsing, which is why those packages appear in the dependency list rather than being optional niceties. If a page blocks automated fetching or renders entirely in JavaScript, the title you get will be whatever the HTML contains.

Search is the part the README spends the most words on: multiple search options including regex and a deep scan mode, described as handy with URLs. Deep scan matters because a normal search matches the stored record, while a URL's meaningful words may sit in the path or query string. There is also continuous search with an on-the-fly mode switch, and smart tag management using redirection operators (>>, >, <<), which lets you rename or merge tags without editing rows by hand.

The project is also a library, with API documentation on Read the Docs, and bukuserver exposes a browsable front-end on a local web host server. The Dockerfile in the repository shows how that server is packaged: it installs /buku[server], runs gunicorn against bukuserver.server:create_app(), and sets BUKUSERVER_PORT to 5001. The README labels the HTTP-based API as for personal use only, which is a fair reading of a single-user tool.

Installing buku and adding your first bookmark

The fastest path is PyPI. The README gives this as the install command, and it pulls the dependencies listed in pyproject.toml.

pip3 install buku

If your distribution package is dated, the README suggests an alternative installation method rather than waiting. From source, the Makefile installs the CLI to /usr/local by default and supports PREFIX if you want a different location.

sudo make install

To remove that installation, the Makefile provides a matching target.

sudo make uninstall

There is also a standalone path that needs no install step at all. From the directory containing the script, the README shows these two commands.

chmod +x buku.py
./buku.py

A first real use, once the command is on your path, is to import what your browser already has. The README lists Firefox, Chrome, Chromium, Vivaldi, Brave, and MS Edge among the supported import sources, so the flag you pick depends on which profile you want. After the import, the database holds titles and URLs; tags are yours to add. If you would rather start clean, adding a single URL fetches its title and description from the web, which is the behaviour the features list leads with.

For shell completion, the repository keeps scripts for Bash, Fish, and Zsh under auto-completion/, and the README points to your shell's manual for installation instructions rather than restating them.

Where buku gets in your way

Title and description fetching is a network operation with all the usual failure modes. A paywalled article, a page behind a login, or a site that serves an empty shell to non-browser clients will produce a thin record. The README does not document a retry policy or a fallback title beyond what the HTML provides, so the honest expectation is that some fraction of your imports will need manual editing. The README anticipates this by pointing at editor integration, which is the intended correction path rather than a bug report.

Broken links are handled by looking them up on the Wayback Machine. That is a useful feature and also a limitation: it tells you an archived copy exists, not that the original is alive. If your workflow depends on knowing whether a URL currently resolves, buku is not that tool.

Encryption is described as manual, and cryptography is a dependency. Manual means you decide when to encrypt and presumably manage the passphrase yourself. Anyone expecting transparent at-rest encryption of the whole database should read the operational notes on the wiki before assuming it works that way; the README does not spell out the threat model.

The front-end is explicitly scoped to personal use. Running bukuserver on a port reachable from the internet is not what the README describes, and the Dockerfile binds gunicorn to 0.0.0.0 inside the container, which is a container-networking detail rather than an invitation to expose it. Treat the web UI as a local convenience.

Finally, the project is GPL-3.0-or-later. That matters if you plan to use buku as a library inside something you distribute, because the licence travels with the code. The README and pyproject.toml both state the licence; neither offers an alternative licensing path.

buku against a self-hosted bookmark service

The closest alternative class is a self-hosted web application such as Linkwarden or Karakeep, both of which appear in the related searches around this project. The difference is architectural, not cosmetic. Those tools run as a service, usually with a database server and a web front-end, and they assume you will reach them over a network from multiple devices. They tend to offer richer capture, including page snapshots and shared collections.

buku inverts that. The primary interface is a command, the primary artifact is a file, and the server component is optional and explicitly personal. There is no account system in the CLI, no multi-user model, and no background service to keep running. If your laptop is offline, buku still searches. If you want to sync, you copy the database, which the README calls out as a design goal.

The trade-off is real in both directions. A service gives you a URL you can open on a phone and a UI someone else maintains. buku gives you grep-ability, regex search, scriptability, and the ability to diff your bookmark store in git if you export it. The README lists export formats including HTML, XBEL, Markdown, RSS/Atom, and Orgfile, so moving data out is not a lock-in problem. Choosing between them is mostly a question of whether you want a place to visit or a file to own.

Maintenance, releases, and upgrade cost

The repository is not archived, and the last push was on 2026-09-15. Release cadence in the recent record is uneven: v4.9 in April 2024, v5.0 in April 2025, v5.1 in December 2025. That is roughly one significant release a year with an occasional second, which is normal for a mature single-maintainer utility and also means you should not expect rapid feature turnover.

Upgrade cost is low by construction. The CLI is one script installed by make, and the PyPI package carries the same dependencies. There is no migration daemon and no server to restart unless you opted into bukuserver. The risk sits in the database schema: a major version bump could change how an existing SQLite file is read, and the README does not document a rollback procedure. If you keep years of bookmarks in one file, copying it before a major upgrade is the cheap insurance, and the export formats give you a second escape hatch.

Dependency drift is the other ongoing cost. urllib3 is pinned below 3, cryptography has a minimum version, and requires-python is >=3.10. Running the standalone buku.py with the chmod +x and ./buku.py commands from the README means you manage those dependencies yourself rather than through a package manager.

On licensing: GPL-3.0-or-later is stated in pyproject.toml and the LICENSE file. Using the CLI to manage your own bookmarks is unremarkable. Embedding the library in a distributed product brings copyleft obligations, and that is a question for your own counsel, not something the README resolves.

Editorial conclusion

Adopt buku if you live in a terminal, want a single file you can copy between machines, and care more about regex search than about thumbnails. Skip it if you need mobile sync, collaborative folders, or a hosted service. Before committing, run buku -p on a copy of your existing database, confirm which browser profiles buku detects on your machine, and decide whether the GPL-3.0-or-later licence fits how you plan to ship anything built on the library.

Frequently asked questions

Official sources

1. Issues
2. jarun/buku on GitHub
3. License: GPL-3.0
4. README
5. Releases