bibtui 0.12.0

A quiet, powerful home for your references.

bibtui

A quiet, powerful home for your references.

Quick start

# Run without installing (opens built-in file browser)
uvx --prerelease=allow bibtui

# Or open a specific .bib directly
uvx --prerelease=allow bibtui myrefs.bib

# Or install permanently
uv tool install --prerelease=allow bibtui

You can now start bibtui without passing a .bib file and select one via the built-in file browser.

Why --prerelease=allow? bibtui depends on bibtexparser v2, which is still in beta on PyPI. This flag tells uv to use it. Once bibtexparser publishes a stable v2 release this flag will no longer be needed.

---

PDF fetching

BibTui can fetch PDFs automatically on import, for individual records, or for your entire library. It uses only free and legal sources: arXiv, Unpaywall, and OpenAlex. For best results, provide an email address for Unpaywall and a free API key for OpenAlex.

Screenshots

Light theme	Dark — Catppuccin Mocha

Nord — keywords modal

---

bibtui is a beautiful, keyboard-driven terminal app for researchers who live in the terminal. Browse and edit your .bib file, fetch open-access PDFs with a single keystroke, track what you've read, and never leave the command line — no database, no sync daemon, no account required.

Mouse users welcome. bibtui works fully with the mouse — click, scroll, select. You just need to launch it from a terminal: uvx --prerelease=allow bibtui (then pick your file in the built-in browser, or pass a path directly).

---

Why bibtui?

	bibtui	JabRef	Zotero
Runs in the terminal	✅	❌	❌
No database / sync daemon	✅	✅	❌
Git-friendly plain .bib	✅	✅	❌
Works over SSH	✅	❌	❌
Full Textual theming	✅	❌	❌
Pure Python, installs less than 1s	✅	❌	❌

Well, I mostly built this for myself. I was trying many bibliography tools over the years and in the end stuck with JabRef. It worked directly on the bib file, had import from DOI, PDF fetching, ratings and PDF linking. What I did not like was the UI and the many features I don't need. Anyway, I kept using it, more or less frustrated.

Then I switched to Linux on my MacBook M1 and suddenly couldn't install JabRef anymore, even after trying different approaches. That was it, I decided to make my own that does what I want, looks nice, and nothing more.

I also wanted to try out Claude Code for a project from scratch, so yes, most of the code was AI-generated. Otherwise I would never have done it. It still took many hours of work and I used my experience from many Python projects. I reviewed everything and have tests for the non ui part.

---

Features

• Browse & search — instant search across title, author, keywords, journals and cite key
• Import by DOI — paste a DOI and metadata is fetched automatically
• Fetch PDFs automatically — tries arXiv → Copernicus → OpenAlex (free tier by default; API key optional) → Unpaywall → direct URL
• Library-wide actions — fetch all missing PDFs and unify citekeys to AuthorYear
• Add existing PDFs — pick a file from your Downloads folder with a live filter
• Edit entries — field-by-field form or raw BibTeX editor (toggle with v)
• Read states & priorities — track what you've read and what matters most
• Star ratings — rate entries 1–5
• Keywords editor — manage tags inline
• JabRef-compatible — file links use JabRef conventions; open the same .bib in both tools
• Git-friendly — it's a plain text file (.bib); commit, diff, and collaborate normally
• Full Textual theme support — including automatic detection of the omarchy themes
• Works anywhere uv does — SSH, HPC clusters, a colleague's laptop
• Built-in file browser — start with or without pointing to a .bib file

---

Installation

Recommended — uv (fastest)

uv tool install --prerelease=allow bibtui

updating an existing installation:

uv tool upgrade bibtui

pip

pip install --pre bibtui

Try without installing

uvx --prerelease=allow bibtui references.bib

Note: The --prerelease=allow / --pre flag is needed because bibtui depends on bibtexparser v2, which is currently in beta on PyPI. Once it releases a stable v2 this flag will no longer be required.

---

Usage

bibtui MyCollection.bib

On first launch bibtui shows a short onboarding wizard that pre-fills sensible defaults for your PDF directory, Downloads folder, and Unpaywall email (no registration required — the email is only used for rate-limiting).

---

PDF workflow

f tries these sources in order:

1. arXiv — for entries with a 10.48550/arXiv.* DOI or an arxiv.org URL
2. Copernicus — direct PDF URL construction for 10.5194/* DOIs
3. OpenAlex — open-access lookup by DOI/title using the free tier by default; add an API key in Settings for higher limits. If free-tier limits are hit (HTTP 429), bibtui tells you explicitly.
4. Unpaywall — free open-access lookup by DOI (set your email in Settings; no account needed)
5. Direct URL — if the entry's url field points directly to a PDF

PDFs are saved to your configured base directory and the entry's file field is updated automatically in JabRef format.

---

Philosophy

• Your .bib file is the source of truth
• No hidden database
• No setup, point and shoot possible
• No lock-in
• No accounts
• keyboard and mouse support
• nice looking
• focused featurset. For cleanup use bibtex-tidy or work directly on the bib file

Development

git clone https://github.com/tgoelles/bib_tui
cd bib_tui
uv sync
uv run bibtui tests/bib_examples/MyCollection.bib

Run the tests:

uv run pytest -m "not network"

Live-reload during development:

uv run textual run --dev src/bibtui/main.py -- tests/bib_examples/MyCollection.bib

---

Related tools

• JabRef — GUI reference manager, same .bib format
• cobib — another terminal BibTeX manager
• bibman — minimal TUI reference manager
• bibiman - A TUI for fast and simple interacting with your BibLaTeX database

---

FAQ

Does this modify my .bib formatting? Yes. but we also write a backup file

Can I use it alongside JabRef or XYZ tool for .bib? Yes. they both just read bib files and bibtui follows JabRef conventions.