:bookmark: Browser-independent bookmark manager
buku in action!
buku is a powerful bookmark manager and a personal textual mini-web.
For those who prefer the GUI, bukuserver exposes a browsable front-end on a local web host server. See bukuserver page for config and screenshots.
When I started writing it, I couldn’t find a flexible command-line solution with a private, portable, merge-able database along with seamless GUI integration. Hence, buku.
buku can import bookmarks from browser(s) or fetch the title, tags and description of a URL from the web. Use your favourite editor to add, compose and update bookmarks. Search bookmarks instantly with multiple search options, including regex and a deep scan mode (handy with URLs).
It can look up broken links on the Wayback Machine. There’s an Easter Egg to revisit random bookmarks.
There’s no tracking, hidden history, obsolete records, usage analytics or homing.
To get started right away, jump to the Quickstart section. buku has one of the best documentation around. The man page comes with examples. For internal details, please refer to the operational notes.
buku is a library too! There are several related projects, including a browser plug-in.
| Feature | Dependency |
|---|---|
| Lang, SQLite | Python 3.8+ |
| HTTPS | certifi, urllib3 |
| Encryption | cryptography |
| HTML | beautifulsoup4, html5lib |
To copy URL to clipboard buku uses xsel (or xclip) on Linux, pbcopy (default installed) on OS X, clip (default installed) on Windows, termux-clipboard on Termux (terminal emulation for Android), wl-copy on Wayland. If X11 is missing, GNU Screen or tmux copy-paste buffers are recognized.
To install buku with all its dependencies from PyPI, run:
# pip3 install buku
You can also install buku from your package manager. If the version available is dated try an alternative installation method.
Auto-generated packages (with only the cli component) for Arch Linux, CentOS, Debian, Fedora, openSUSE Leap and Ubuntu are available with the latest stable release.
NOTE: CentOS may not have the python3-beautifulsoup4 package in the repos. Install it using pip3.
If you have git installed, clone this repository. Otherwise download the latest stable release or development version (risky).
Install the dependencies. For example, on Ubuntu:
$ apt-get install ca-certificates python3-urllib3 python3-cryptography python3-bs4
Install the cli component to default location (/usr/local):
$ sudo make install
To remove, run:
$ sudo make uninstall
PREFIX is supported, in case you want to install to a different location.
buku is a standalone utility. From the containing directory, run:
$ chmod +x buku$ ./buku
Shell completion scripts for Bash, Fish and Zsh can be found in respective subdirectories of auto-completion/. Please refer to your shell’s manual for installation instructions.
usage: buku [OPTIONS] [KEYWORD [KEYWORD ...]]Bookmark manager like a text-based mini-web.POSITIONAL ARGUMENTS:KEYWORD search keywordsGENERAL OPTIONS:-a, --add URL [+|-] [tag, ...]bookmark URL with comma-separated tags(prepend tags with '+' or '-' to use fetched tags)-u, --update [...] update fields of an existing bookmarkaccepts indices and rangesrefresh title and desc if no edit optionsif no arguments:- update results when used with search- otherwise refresh all titles and desc-w, --write [editor|index]edit and add a new bookmark in editorelse, edit bookmark at index in EDITORedit last bookmark, if index=-1if no args, edit new bookmark in EDITOR-d, --delete [...] remove bookmarks from DBaccepts indices or a single rangeif no arguments:- delete results when used with search- otherwise delete all bookmarks--retain-order prevents reordering after deleting a bookmark-h, --help show this information and exit-v, --version show the program version and exitEDIT OPTIONS:--url keyword bookmark link--tag [+|-] [...] comma-separated tagsclear bookmark tagset, if no arguments'+' appends to, '-' removes from tagset--title [...] bookmark title; if no arguments:-a: do not set title, -u: clear title-c, --comment [...] notes or description of the bookmarkclears description, if no arguments--immutable N disable web-fetch during auto-refreshN=0: mutable (default), N=1: immutable--swap N M swap two records at specified indicesSEARCH OPTIONS:-s, --sany [...] find records with ANY matching keywordthis is the default search option-S, --sall [...] find records matching ALL the keywordsspecial keywords -"blank": entries with empty title/tag"immutable": entries with locked title--deep match substrings ('pen' matches 'opens')--markers search for keywords in specific fieldsbased on (optional) prefix markers:'.' - title, '>' - description, ':' - URL,'#' - tags (comma-separated, PARTIAL matches)'#,' - tags (comma-separated, EXACT matches)'*' - any field (same as no prefix)-r, --sreg expr run a regex search-t, --stag [tag [,|+] ...] [- tag, ...]search bookmarks by tagsuse ',' to find entries matching ANY taguse '+' to find entries matching ALL tagsexcludes entries with tags after ' - 'list all tags, if no search keywords-x, --exclude [...] omit records matching specified keywords--random [N] output random bookmarks out of the selection (default 1)--order fields [...] comma-separated list of fields to order the output by(prepend with '+'/'-' to choose sort direction)ENCRYPTION OPTIONS:-l, --lock [N] encrypt DB in N (default 8) # iterations-k, --unlock [N] decrypt DB in N (default 8) # iterationsPOWER TOYS:--ai auto-import bookmarks from web browsersFirefox, Chrome, Chromium, Vivaldi, Edge-e, --export file export bookmarks to Firefox format HTMLexport XBEL, if file ends with '.xbel'export Markdown, if file ends with '.md'format: [title](url) <!-- TAGS -->export Orgfile, if file ends with '.org'format: *[[url][title]] :tags:export rss feed if file ends with '.rss'export buku DB, if file ends with '.db'combines with search results, if opted-i, --import file import bookmarks from filesupports .html .xbel .json .md .org .rss .db-p, --print [...] show record details by indices, rangesprint all bookmarks, if no arguments-n shows the last n results (like tail)-f, --format N limit fields in -p or JSON search outputN=1: URL; N=2: URL, tag; N=3: title;N=4: URL, title, tag; N=5: title, tag;N0 (10, 20, 30, 40, 50) omits DB index-j, --json [file] JSON formatted output for -p and search.prints to stdout if argument missing.otherwise writes to given file--colors COLORS set output colors in five-letter string--nc disable color output-n, --count N show N results per page (default 10)--np do not show the subprompt, run and exit-o, --open [...] browse bookmarks by indices and rangesopen a random bookmark, if no arguments--oa browse all search results immediately--replace old new replace old tag with new tag everywheredelete old tag, if new tag not specified--url-redirect when fetching an URL, use the resultingURL from following *permanent* redirects(when combined with --export, the old URLis included as additional metadata)--tag-redirect [tag] when fetching an URL that causes permanentredirect, add a tag in specified pattern(using 'http:{}' if not specified)--tag-error [tag] when fetching an URL that causes an HTTPerror, add a tag in specified pattern(using 'http:{}' if not specified)--del-error [...] when fetching an URL causes any (given)HTTP error, delete/do not add it--export-on [...] export records affected by the aboveoptions, including removed info(requires --update and --export; specificHTTP response filter can be provided)--cached index|URL browse a cached page from Wayback Machine--offline add a bookmark without connecting to web--suggest show similar tags when adding bookmarks--tacit reduce verbosity, skip some confirmations--nostdin do not wait for input (must be first arg)--threads N max network connections in full refreshdefault N=4, min N=1, max N=10-V check latest upstream version available-g, --debug show debug information and verbose logsSYMBOLS:> url+ comment# tagsPROMPT KEYS:1-N browse search result indices and/or rangesR [N] print out N random search results(or random bookmarks if negative or N/A)^ id1 id2 swap two records at specified indicesO [id|range [...]] open search results/indices in GUI browsertoggle try GUI browser if no argumentsa open all results in browsers keyword [...] search for records with ANY keywordS keyword [...] search for records with ALL keywordsd match substrings ('pen' matches 'opened')m search with markers - search string is splitinto keywords by prefix markers, which determinewhat field the keywords is searched in:'.', '>' or ':' - title, description or URL'#'/'#,' - tags (comma-separated, partial/full match)'*' - all fields (can be omitted in the 1st keyword)note: tag marker is not affected by 'd' (deep search)v fields change sorting order (default is '+index')multiple comma/space separated fields can be specifiedr expression run a regex searcht [tag, ...] search by tags; show taglist, if no argsg taglist id|range [...] [>>|>|<<] [record id|range ...]append, set, remove (all or specific) tagssearch by taglist id(s) if records are omittedn show next page of search resultsN show previous page of search resultso id|range [...] browse bookmarks by indices and/or rangesp id|range [...] print bookmarks by indices and/or rangesw [editor|id] edit and add or update a bookmarkc id copy URL at search result index to clipboard? show this helpq, ^D, double Enter exit buku
buku supports custom colors. Visit the wiki page on how to customize colors for more details.
VISUAL or EDITOR to point to your favourite editor. Note that VISUAL takes precedence over EDITOR.Create a sweeter shortcut with some convenience.
alias b='buku --suggest'
Auto-import bookmarks from your browser(s). Please quit the relevant browsers beforehand to ensure the databases are not locked.
b --ai
Manually add a bookmark (for hands-on).
b -w
List your bookmarks with DB index.
b -p
Quick (bash/zsh) commands to fuzzy search with fzf and open the selection in Firefox:
firefox $(buku -p -f 10 | fzf)firefox $(buku -p -f 40 | fzf | cut -f1)
POSIX script to show a preview of the bookmark as well:
#!/usr/bin/env shurl=$(buku -p -f4 | fzf -m --reverse --preview "buku -p {1}" --preview-window=wrap | cut -f2)if [ -n "$url" ]; thenecho "$url" | xargs firefoxfi
Edit and add a bookmark from editor:
$ buku -w$ buku -w 'gedit -w'$ buku -w 'macvim -f' -a https://ddg.gg search engine, privacy
The first command picks editor from the environment variable EDITOR. The second command opens gedit in blocking mode. The third command opens macvim with option -f and the URL and tags populated in template.
Add a simple bookmark:
$ buku --nostdin -a https://github.com/2648. GitHub: Let’s build from here · GitHub> https://github.com/+ GitHub is where over 94 million developers shape the future of software, together. Contribute to the open source community, manage your Git repositories, review code like a pro, track bugsand features, power your CI/CD and DevOps workflows, and secure code before you commit it.$ buku --nostdin -a https://github.com/[ERROR] URL [https://github.com/] already exists at index 2648
>: URL, +: comment, #: tags
Title, description and tags will be fetched from site. Buku only stores unique URLs and will raise error if the URL already present in the database:
Add a bookmark with tags search engine and privacy, comment Search engine with perks, fetch page title from the web:
$ buku -a https://ddg.gg search engine, privacy -c Search engine with perks336. DuckDuckGo> https://ddg.gg+ Alternative search engine with perks# privacy,search engine
where, >: URL, +: comment, #: tags
Add a bookmark with tags search engine & privacy and immutable custom title DDG:
$ buku -a https://ddg.gg search engine, privacy --title 'DDG' --immutable 1336. DDG (L)> https://ddg.gg# privacy,search engine
Note that URL must precede tags.
Add a bookmark without a title (works for update too):
$ buku -a https://ddg.gg search engine, privacy --title
Edit and update a bookmark from editor:
$ buku -w 15012014
This will open the existing bookmark’s details in the editor for modifications. Environment variable EDITOR must be set.
Update existing bookmark at index 15012014 with new URL, tags and comments, fetch title from the web:
$ buku -u 15012014 --url http://ddg.gg/ --tag web search, utilities -c Private search engine
Fetch and update only title for bookmark at 15012014:
$ buku -u 15012014
Update only comment for bookmark at 15012014:
$ buku -u 15012014 -c this is a new comment
Applies to —url, —title and —tag too.
Export bookmarks tagged tag 1 or tag 2 to HTML, XBEL, Markdown, Orgfile or a new database:
$ buku -e bookmarks.html —stag tag 1, tag 2
$ buku -e bookmarks.xbel —stag tag 1, tag 2
$ buku -e bookmarks.md —stag tag 1, tag 2
$ buku -e bookmarks.org —stag tag 1, tag 2
$ buku -e bookmarks.db —stag tag 1, tag 2
All bookmarks are exported if search is not opted.
Import bookmarks from HTML, XBEL, Markdown or Orgfile:
$ buku -i bookmarks.html$ buku -i bookmarks.xbel$ buku -i bookmarks.md$ buku -i bookmarks.org$ buku -i bookmarks.db
Delete only comment for bookmark at 15012014:
$ buku -u 15012014 -c
Applies to —title and —tag too. URL cannot be deleted without deleting the bookmark.
Update or refresh full DB with page titles from the web:
$ buku -u$ buku -u --tacit (show only failures and exceptions)
This operation can update the title or description fields of non-immutable bookmarks by parsing the fetched page. Fields are updated only if the fetched fields are non-empty. Tags remain untouched.
Delete bookmark at index 15012014:
$ buku -d 15012014Index 15012020 moved to 15012014
The last index is moved to the deleted index to keep the DB compact. Add --tacit to delete without confirmation.
Delete all bookmarks:
$ buku -d
Delete a range or list of bookmarks:
$ buku -d 100-200$ buku -d 100 15 200
Search bookmarks for ANY of the keywords kernel and debugging in URL, title or tags:
$ buku kernel debugging$ buku -s kernel debugging
Search bookmarks with ALL the keywords kernel and debugging in URL, title or tags:
$ buku -S kernel debugging
Search bookmarks tagged general kernel concepts:
$ buku --stag general kernel concepts
Search for bookmarks matching ANY of the tags kernel, debugging, general kernel concepts:
$ buku --stag kernel, debugging, general kernel concepts
Search for bookmarks matching ALL of the tags kernel, debugging, general kernel concepts:
$ buku --stag kernel + debugging + general kernel concepts
Search for bookmarks matching any of the keywords hello or world, excluding the keywords real and life, matching both the tags kernel and debugging, but excluding the tags general kernel concepts and books:
$ buku hello world --exclude real life --stag 'kernel + debugging - general kernel concepts, books'
Search for bookmarks with different tokens for each field, and print them out sorted by the tags (ascending) and URL (descending)
$ buku --order +tags,-url --markers --sall 'global substring' '.title substring' ':url substring' :https '> description substring' '#partial,tags:' '#,exact,tags' '*another global substring'
List all unique tags alphabetically:
$ buku --stag
Run a search and update the results:
$ buku -s kernel debugging -u --tag + linux kernel
Run a search and delete the results:
$ buku -s kernel debugging -d
Encrypt or decrypt DB with custom number of iterations (15) to generate key:
$ buku -l 15$ buku -k 15
The same number of iterations must be specified for one lock & unlock instance. Default is 8, if omitted.
Show details of bookmarks at index 15012014 and ranges 20-30, 40-50:
$ buku -p 20-30 15012014 40-50
Show details of the last 10 bookmarks:
$ buku -p -10
Show all bookmarks with real index from database:
$ buku -p$ buku -p | more
Replace tag ‘old tag’ with ‘new tag’:
$ buku --replace 'old tag' 'new tag'
Delete tag ‘old tag’ from DB:
$ buku --replace 'old tag'
Append (or delete) tags ‘tag 1’, ‘tag 2’ to (or from) existing tags of bookmark at index 15012014:
$ buku -u 15012014 --tag + tag 1, tag 2$ buku -u 15012014 --tag - tag 1, tag 2
Open URL at index 15012014 in browser:
$ buku -o 15012014
List bookmarks with no title or tags for bookkeeping:
$ buku -S blank
List bookmarks with immutable title:
$ buku -S immutable
Append, remove tags at prompt (taglist index to the left, bookmark index to the right):
// append tags at taglist indices 4 and 6-9 to existing tags in bookmarks at indices 5 and 2-3buku (? for help) g 4 9-6 >> 5 3-2// set tags at taglist indices 4 and 6-9 as tags in bookmarks at indices 5 and 2-3buku (? for help) g 4 9-6 > 5 3-2// remove all tags from bookmarks at indices 5 and 2-3buku (? for help) g > 5 3-2// remove tags at taglist indices 4 and 6-9 from tags in bookmarks at indices 5 and 2-3buku (? for help) g 4 9-6 << 5 3-2
List bookmarks with colored output:
$ buku --colors oKlxm -p
Add a bookmark after following all permanent redirects, but only if the server doesn’t respond with an error (and there’s no network failure)
$ buku --add http://wikipedia.net --url-redirect --del-error2. Wikipedia> https://www.wikipedia.org/+ Wikipedia is a free online encyclopedia, created and edited by volunteers around the world and hosted by the Wikimedia Foundation.
Add a bookmark with tag http redirect if the server responds with a permanent redirect, or tag shaped like http 404 on an error response:
$ buku --add http://wikipedia.net/notfound --tag-redirect 'http redirect' --tag-error 'http {}'[ERROR] [404] Not Found3. Not Found> http://wikipedia.net/notfound# http 404,http redirect
Update all bookmarks matching the search by updating the URL if the server responds with a permanent redirect, deleting the bookmark if the server responds with HTTP error 400, 401, 402, 403, 404 or 500, or adding a tag shaped like http:{} in case of any other HTTP error; then export those affected by such changes into an HTML file, marking deleted records as well as old URLs for those replaced by redirect.
$ buku -S ://wikipedia.net -u --url-redirect --tag-error --del-error 400-404,500 --export-on --export backup.html
Print out a single random bookmark:
$ buku --random --print
Print out 3 random bookmarks ordered by netloc (reversed), title and url:
$ buku --random 3 --order ,-netloc,title,+url --print
Print out a single random bookmark matching search criteria, and export into a Markdown file (in DB order):
$ buku --random -S kernel debugging --export random.md
Swap positions of records #4 and #5:
$ buku --swap 4 5
More help:
$ buku -h$ man buku
Interactive workflows can be automated using expect. Issue #368 has a working example on automating auto-import.
You may encounter issues with GUI editors which maintain only one instance by default and return immediately from other instances. Use the appropriate editor option to block the caller when a new document is opened. See issue #210 for gedit.
Copyright © 2015-2025 Arun Prakash Jana
Missing a feature? There’s a rolling ToDo List with identified tasks. Contributions are welcome! Please follow the PR guidelines.
See also our documentation here 