Help & Troubleshooting

If sudo apt install ./grace-b2u_<version>_all.deb fails with:

grace-b2u : Depends: python3 (>= 3.12) but 3.10.x is to be installed
E: Unable to correct problems, you have held broken packages.

your distribution is older than Grace's minimum. The .deb requires Python 3.12, which ships on Ubuntu 24.04 (Noble) and newer, Linux Mint 22+, and Debian 13+. On Ubuntu 22.04 (Jammy) the newest python3 is 3.10, so apt cannot satisfy the dependency and refuses the install.

Two ways forward:

1. Upgrade the operating system to a 24.04-era release (or newer Mint / Debian), then re-run the install.
2. Run Grace from source in a virtual environment built on a Python 3.12 you install yourself — Grace itself does not care which distro it runs on, only that Python is 3.12+.

This is not a packaging bug: the version string 3.10.6-1~22.04.1 in the error is the tell that the machine is on 22.04.

Hand the local .deb to apt, not dpkg:

sudo apt install ./grace-b2u_<version>_all.deb

The leading ./ is required — without a path-like argument apt looks the name up in the configured archives and will not find grace-b2u (it is ours, not in any repo).

apt resolves and pulls every Depends: line automatically. By contrast dpkg -i unpacks the package but leaves it unconfigured if any dependency is missing, forcing you to run sudo apt --fix-broken install afterwards.

Grace's .deb depends on the distribution's python3-pyside6.* packages rather than bundling Qt. Ubuntu 24.04 ships PySide6 6.6.x, which Grace tolerates. If a target distro does not yet package PySide6, the Depends: line includes a | python3-pyside2.* fallback.

If the GUI fails to start with a Qt platform-plugin error, make sure a desktop session (X11 or Wayland) is available — the grace --headless entry point is the only mode that needs no display server.

Grace's macOS .app is not yet signed with an Apple Developer ID (signing is deferred until one is acquired), so Gatekeeper may refuse the first launch.

To open it anyway: right-click (or Control-click) Grace.app in Finder, choose Open, then confirm Open in the dialog. macOS remembers the exception for subsequent launches. Alternatively, allow it under System Settings → Privacy & Security after the first blocked attempt.

Because the Windows installer is not yet code-signed, Microsoft Defender SmartScreen may show a "Windows protected your PC" warning on first run.

If you trust the download, click More info, then Run anyway. The portable .zip build avoids the installer entirely — unzip it and run the executable directly.

If launching Grace seems to do nothing, run it from a terminal with diagnostics enabled to see why:

grace --debug

To confirm the core (non-GUI) code path works at all — useful when a display-server or Qt-plugin problem is suspected — run the headless smoke path, which needs no window:

grace --headless --debug

If the headless path succeeds but the GUI does not, the problem is the Qt/desktop environment, not Grace's data or settings.

The Flatpak build runs in a sandbox, so paths differ from the .deb:

• Notes and downloaded content — your real Documents folder: ~/Documents/Grace/Notes, ~/Documents/Grace/Commentaries, …/Books, …/Dictionaries. Grace ships with the narrow xdg-documents permission so these work exactly like the .deb. This is where you save files downloaded from the Content page.
• Database, preferences, logs — inside the per-app sandbox dir: ~/.var/app/app.grace.b2u.Grace/ (data/Grace/grace.db, config/Grace/preferences.toml).

Do NOT copy downloaded .sqlite files into the install dir (~/.local/share/flatpak/app/app.grace.b2u.Grace/.../files/). That is the read-only bundled data and it is erased on every Flatpak update. Put downloads in ~/Documents/Grace/… instead.

You can point any folder elsewhere in Settings → Preferences → Paths; pick the folder with the Browse… button so the sandbox grants access. Custom folders are most reliable under Documents.

Grace is a local-first Bible research and analysis tool. Everything lives on your computer:

• Bible text and cross-references are stored in a local SQLite database.
• Notes are written to your Documents folder.
• No cloud sync, no telemetry, no startup network calls.

Open Help → About Grace… for the version + license summary.

On first launch the First-Run Wizard asks for two things:

1. Theme + language — pick a color theme and the UI language. Theme changes apply live; language changes need a restart.
2. Bundled translations — the wizard offers the bundled KJV (1769) plus a cross-reference set (~432,000 links). Both are pre-checked.

If you skip a step you can rerun it later:

• File → Import Bundled Data… — re-imports the bundled KJV.
• Downloads → Bible Translations… — installs additional shipped translations (Coverdale, Bishops', Tyndale, Geneva, KJV with Strong's).

The main window has one central reader area surrounded by three dock panels:

• Library (left) — every imported Bible / dataset.
• Annotations (right) — your highlights and notes for the current verse.
• Search (bottom) — full-text search box and results.

Docks can be dragged, tabified, or floated. To restore defaults: View → Reset Panel Layout (docks) or View → Reset Window Geometry (window size + position).

Edit → Go to Reference… (Ctrl+G) opens a small dialog. Type a reference like Rom 3:23, Genesis 1:1, or 1 John 4:8 — every standard Protestant 66-book name and common abbreviation is accepted.

When you press OK the reader scrolls to the verse, briefly flashes a blue highlight, and leaves a subtle persistent tint so you can re-find the verse after scrolling away.

Adjust the reader, compare, and annotation font size live:

• Ctrl+= (or Ctrl++) — zoom in.
• Ctrl+- — zoom out.
• Ctrl+0 — reset to the size set in Preferences.

The library panel uses its own size from Settings → Preferences → General → Library font size.

Settings → Preferences → General → Theme offers seven curated themes plus System (uses your OS default).

• Light: Neutral, GitHub, Solarized, Reading Ergonomic.
• Dark: GitHub, Solarized, Reading Ergonomic.

Theme changes apply immediately. Strong's number anchors and highlights are theme-aware so they remain readable on every background.

Open the Search dock (Ctrl+F) and type. The search uses SQLite FTS5 over every imported translation; matches return in milliseconds even for 90,000-verse libraries.

Three modes via the mode combo:

• All words — every typed word must appear (any order).
• Exact phrase — words must appear adjacent in this order.
• Any word — at least one word matches.

Toggle Case sensitive for an exact-case post-filter. Click any result to jump the reader to that verse.

• A bare two-word query searches for either word (default All-words mode requires both).
• Quote a phrase to force adjacency: "in the beginning".
• A trailing * is treated as a prefix: proph* matches prophet, prophecy, etc.
• Diacritics are ignored: agape matches ágape.
• The Search panel scopes to the currently-selected source(s) in the Library when more than one translation is imported.

View → Compare (Ctrl+Shift+C) splits the reader into side-by-side panes. Pick translations from the per-pane source selector at the top of each pane.

When exactly two panes are visible, word-level differences between the chosen translations are highlighted in yellow. View → Swap Compare Panes (Ctrl+Alt+S) flips the two visible panes.

The bundled cross-reference set (~432,000 links from the Treasury of Scripture Knowledge) drives the Annotations dock's See also list. Clicking a referenced verse jumps the reader there. Cross-references import automatically with the first-run wizard or via File → Import Bundled Data….

Select text in the reader and right-click → Highlight… to pick a color. Highlights persist across sessions and are stored in the local annotations table; deleting the source translation cascades to its highlights.

Position the cursor on a verse and pick Edit → New Note (Ctrl+N) — or right-click the verse → Add Note…. The Annotations dock surfaces every note attached to the current verse. Notes can be exported alongside highlights via File → Export….

The richer Notes & Document Tools subsystem (full Markdown editor, exports to PDF / DOCX / ODT) lives outside the per-verse note system — see Notes and Documents below.

Grace ships a full notes system separate from the per-verse annotations. Notes live as Markdown files on your disk under ~/Documents/Grace/Notes (configurable via Settings → Notes Library Folder…) so you can back them up, sync them, or open them in any text editor.

Use the Notes panel (toggle via View → Show Notes Panel) to:

• create / rename / move / delete notes
• search the body of every note
• add tags, status, opinion rating, and Bible references
• export to TXT / XLSX / PDF / ODT / DOCX
• open the note in LibreOffice for heavy authoring.

Select a note in the Notes panel and pick File → Export Note… (Ctrl+Shift+E).

• TXT — pure plain text. Always available.
• XLSX — Metadata + Body sheets via openpyxl. Always available.
• PDF — uses LibreOffice when present; falls back to the built-in Qt renderer otherwise.
• ODT / DOCX — needs LibreOffice. If LO is missing, the action greys out with an install hint, or you can opt into the Allow lossy fallback exporters checkbox under Settings → Advanced.

File → Open Note in LibreOffice (Source) (Ctrl+Shift+L) hands the canonical Markdown file to LibreOffice in its own window. Grace watches the file's modification time and offers to reload your buffer after each LO save.

File → Open Note in LibreOffice (Preview) (Ctrl+Alt+L) renders the in-app preview to a temp ODT (with images and video links inline) and opens that in LO.

If LibreOffice is not installed, both actions are disabled with a tooltip pointing at https://libreoffice.org.

The Notes panel's search bar mirrors the Bible search engine: All words / Exact phrase / Any word modes plus a case-sensitive toggle. The selected folder in the tree acts as the search scope — pick All Notes for the whole library or a sub-folder to narrow.

Deleting a note moves it to a _trash/ sub-folder under the library root and removes it from the catalog. Use the Trash… button in the Notes panel toolbar to view, restore, or permanently purge entries.

Trashed notes are auto-purged after 30 days by default. Restore replays the same code path the GUI uses to ingest any other on-disk file, so the restored note is indistinguishable from a hand-created one.

Strong's numbers (e.g. H7225, G3056) link an English word to its underlying Hebrew or Greek lexeme. Grace shows them as small superscript anchors after each tagged word in the reader; clicking one opens the Strong's side dock with the lemma, transliteration, pronunciation, definition, and KJV usage.

View → Show Strong's Numbers (Ctrl+Shift+S) toggles the anchors. The first time you turn it on without any Strong's-tagged source imported, an onboarding dialog walks you through:

1. Pointing Grace at a folder that contains Strong's data.
2. Scanning that folder for known datasets.
3. Importing whichever ones you want.

The simplest source is the bundled KJV with Strong's translation under Downloads → Bible Translations….

View → Strong's Display picks how the data appears:

• Dock — clicks open the side dock; the verse stays compact.
• Inline — every verse is followed by a list of its Strong's numbers + lemma + short definition.
• Both — inline list plus the dock.

Downloads → Strong's Data… opens a card-per-dataset dialog covering STEPBible (English-tagged NT + OT), OSHB (Hebrew Masoretic OSIS), MorphGNT (Greek SBLGNT), and the OpenScriptures Strong's dictionary.

Each card shows the license, approximate size, upstream URL, and an Install button. Successful downloads auto-run the Strong's scan + import pipeline.

Downloads → Bible Translations… lists six English public-domain translations shipped with the application:

• King James Version (1769) — plain text
• King James Version with Strong's
• Coverdale Bible (1535)
• Bishops' Bible (1568)
• Tyndale Bible (1534)
• Geneva Bible (1587)

Click Install on any card to ingest it into your local database. Cards that are already installed read Installed and the button greys out.

Drop additional Bible-shaped SQLite files (BSS schema or scrollmapper schema) into ~/Grace/Bibles — the default folder Grace auto-creates for user-supplied translations. Reopen Downloads → Bible Translations… and any matching file appears as Available (user folder).

The folder picker at the top of the dialog lets you point elsewhere on a per-session basis. To import an arbitrary file from anywhere on disk, use File → Import… instead.

Grace ships Webster's American Dictionary (1828) (~63,000 headwords) bundled inside the application — no download required. Two more public-domain editions are offered via Downloads → Dictionaries…:

• Webster 1844 (~83,000 headwords)
• Webster 1913 Revised Unabridged (~114,000 headwords)

Each dictionary lives in its own SQLite file with a uniform schema, queried via FTS5 for fast lookups. Source data comes from https://github.com/DataWar/1828-dictionary (MIT-licensed packaging of Public Domain text).

Right-click any word in the Reader or a Compare pane and pick Define "X"… to look it up. The action uses the selected text when you have a selection, otherwise the word under the cursor.

The lookup raises the Dictionary side-dock and renders all senses for the headword. Click the dictionary picker at the top of the dock to switch between installed editions.

Help → Dictionary… opens a non-modal dictionary browser. Type any word into the search box and press Enter to look it up; the dropdown above the search box switches between installed editions.

Closing the dialog does not affect the side-dock — the two surfaces share the same lookup engine but render independently.

Webster 1844 and 1913 are not bundled with the application (they would more than double the installer size). To install them locally, place a webster1844.sqlite or webster1913.sqlite file into ~/Documents/Grace/Dictionaries/ and reopen Downloads → Dictionaries… — the cards flip from File not found to Available (user folder).

Grace ships Adam Clarke's Commentary on the Bible (~21,000 verse entries, 1810–1826) plus five general-book resources: Finney's Sermons, 1 Enoch (R. H. Charles 1906), Jubilees (R. H. Charles 1913), Josephus: The Complete Works (Whiston translation), and the Didache. All Public Domain.

Source: the CrossWire SWORD Project module library, transcoded to SQLite for fast in-app lookup.

Right-click any verse in the Reader or a Compare pane and pick Commentary on "BOOK CHAP:VERSE"… to render Adam Clarke's notes in the Commentary side-dock.

The dock also auto-updates when you navigate the reader via Go to Reference (Ctrl+G) or the book/chapter selector — it follows whatever the reader is showing.

Help → Commentary… raises and focuses the Commentary side-dock; Help → Books… does the same for the Books dock. Both docks appear by default in the left tab band next to Library / Strong's / Dictionary / Notes.

Downloads → Commentaries… and Downloads → Books… list the bundled set as Available (bundled) and include a Browse CrossWire catalog… button that opens https://crosswire.org/sword/modules/ in your browser.

To install an additional Public-Domain module locally, place its .sqlite file into ~/Documents/Grace/Commentaries/ (or ~/Documents/Grace/Books/ for general books) and reopen the dialog — the new card flips from File not found to Available (user folder). (You can change these folders in Settings → Preferences → Paths.)

Always check the module's Distribution License on CrossWire before installing — only modules marked Public Domain (or another license whose terms you can verify) are safe to ship and redistribute.

Settings → Preferences… opens a four-tab dialog:

• General — theme, language, fonts, library font size.
• Reader — verse numbers, flash highlight, current-verse indicator, compare style.
• Research — search defaults (DB IDs in results, etc.) and the Strong's data dir / display preferences.
• Advanced — opt-in fallback exporters, reserved future controls.

Settings are app-wide and persist to preferences.toml. Options (under the Options menu) are per-document / per-session and live only in memory.

Grace's panels (Reader, Compare, Library, Annotations, Search, Notes, Note Editor, Strong's, Dictionary, Commentary, Books) are dockable: drag them by their title bar to rearrange, stack them as tabs, float them, or close them. Once you have an arrangement you like, you can save it as one of three named layouts and switch between them later — handy for reading vs. compare vs. word-study workflows.

Where to find it

Open View → Saved Layouts. The submenu has five groups:

• Save Current As…
• Load
• Set Preferred for Reset
• Delete
• Clear All Saved Layouts

Up to three slots are available (Slot 1, Slot 2, Slot 3). Each slot can be empty, or hold a saved layout with an optional user-supplied name.

Saving a layout

1. Arrange the docks the way you want.
2. View → Saved Layouts → Save Current As… → Slot N.
3. Grace prompts for a name; type something memorable ("Reading", "Word study", "Compare") or accept the default. The Save Current As… and Load menus immediately show the new label.

If a slot already had a layout, saving overwrites it without prompting — there is no undo for the previous contents.

Loading a layout

View → Saved Layouts → Load → Slot N restores that slot's docks and sizes. Empty slots are greyed out.

If a saved layout references a panel that no longer exists (e.g. you saved while a feature was on, then a later release moved it), Grace warns you and leaves the current layout untouched.

Reset Panel Layout — and what "preferred" means

View → Reset Panel Layout is the one-click "go back to a known-good state" button. By default it reverts to the Factory default — the layout Grace ships with.

Set Preferred for Reset changes that target:

• Factory default — Reset reverts to the shipped layout.
• Slot 1 / 2 / 3 — Reset reverts to that saved layout. Empty slots cannot be picked as preferred.

The selected option is checked in the submenu so it is always clear which one Reset will use. Pick whichever arrangement you spend the most time in as the preferred target so a single keystroke takes you back there.

Deleting a saved layout

View → Saved Layouts → Delete → Slot N wipes that slot's body and name. There is no confirmation — the operation is silent and immediate. If you delete the slot that was the preferred Reset target, Grace automatically rolls the preferred pointer back to Factory default and shows a status-bar note so Reset keeps working.

Clear All Saved Layouts wipes all three slots in one step (after a confirmation dialog). This entry is greyed out when there is nothing to clear.

Related: Reset Window Geometry

Saved layouts only cover the dock arrangement inside the main window. View → Reset Window Geometry is a separate command that restores the main window's size and position to the shipped defaults — useful if Grace ends up off-screen after a monitor change.

Where the data lives

Saved layouts persist as base64 dock-state strings in preferences.toml (grace.layout_slot_1, grace.layout_slot_1_name, and so on for slots 2 and 3, plus grace.preferred_layout_slot). They survive restarts, application updates, and OS reboots; they do not sync between machines unless you copy preferences.toml yourself.

Reader / navigation

• Ctrl+G — Go to reference
• Ctrl+F — Focus the search box
• Ctrl+= / Ctrl+- / Ctrl+0 — Zoom in / out / reset
• Ctrl+Shift+C — Toggle compare
• Ctrl+Alt+S — Swap compare panes
• Ctrl+Shift+S — Toggle Strong's numbers

Notes

• Ctrl+N — New note
• Ctrl+S — Save current note
• Ctrl+Shift+S — Save as…
• Ctrl+Shift+E — Export note…
• Ctrl+Shift+L — Open note in LibreOffice (Source)
• Ctrl+Alt+L — Open note in LibreOffice (Preview)

Files

• Ctrl+I — Import…
• Ctrl+E — Export…
• Ctrl+Q — Quit

Grace can check grace-b2u.org to see whether a newer version is available. The feature is off by default and is never run automatically — you choose when to check.

Enable the feature

Open Settings → Preferences → Behavior and tick Enable update checks. The Help → Check for Updates… menu item becomes available; until then it stays disabled.

Run a check

Select Help → Check for Updates…. A confirmation dialog asks before any network call is made; cancel = no request goes out. After you confirm, Grace fetches the version manifest and reports one of:

• Grace is up to date — your running build matches the latest published one. The dialog has a Check Again button that bypasses the 6-hour cache and re-asks for consent before re-fetching.
• Update available — a newer build exists. The dialog shows both the current and latest tags (including beta-build dates when they differ within the same marketing version, e.g. 0.2.1-2026.05.11 → 0.2.1-2026.05.21). Use View Downloads to open grace-b2u.org/downloads in your browser. Grace does not download or install the update automatically.
• You're ahead of the latest release — you're running a development or pre-release build newer than what the site publishes.
• Couldn't check for updates — the request failed (network down, server error, etc.). The dialog shows the HTTP status and the endpoint URL; for network failures it also offers Don't ask again to turn the pref back off in one click.

What gets sent

Exactly four pieces of information ride in the request's User-Agent header:

• Your Grace version (e.g. 0.2.1)
• Operating system (linux / windows / macos)
• CPU architecture (amd64 / arm64 / universal)
• Packaging format (deb / flatpak / windows-installer / windows-portable / macos-dmg / source)

No personal data, no install id, no telemetry.

1. Switch the mode combo to Exact phrase. The default All words mode finds non-adjacent matches but a quoted two-word phrase is the cleanest way to demand adjacency.
2. If the library predates the FTS5 sync hooks, the search index may be empty. Reopen Grace — it auto-rebuilds the FTS table when it detects an empty index against a populated translations table.

LibreOffice is a user-installed prerequisite. Install it from https://libreoffice.org and restart Grace; the locator re-detects on every launch (and once every 24 hours during a session). To point at a non-default install, set the GRACE_LIBREOFFICE environment variable to the absolute soffice binary path before launching Grace.

PDF export does not require LibreOffice — the Qt fallback always works.

If a dock disappears or the layout feels broken:

• View → Reset Panel Layout — restores the docks to first-run defaults without touching the reader, search, or annotations content.
• View → Reset Window Geometry — resizes the main window to 1280×800 and centres it on the primary screen.

Bible text + annotations — grace.db SQLite file under:

• Linux: ~/.local/share/grace/
• macOS: ~/Library/Application Support/Grace/
• Windows: %LOCALAPPDATA%\Grace\

Notes + downloaded commentaries / books / dictionaries — under your Documents folder by default:

• ~/Documents/Grace/Notes
• ~/Documents/Grace/Commentaries, …/Books, …/Dictionaries

All four folders are configurable in Settings → Preferences → Paths.

Preferences — preferences.toml in the same app data directory as the database.

Flatpak users: the sandbox redirects these paths. The app's own database/preferences live under ~/.var/app/app.grace.b2u.Grace/, while your Notes and content use your real ~/Documents/Grace/… (Grace ships with the xdg-documents permission). See Flatpak: where are my files? under Installation.

Back up the SQLite file and the Documents/Grace folder and you have everything.