Libiry

7.7 Troubleshooting

Common issues and solutions for Libiry.

Installation issues

Linux specific: make sure the install file is executable (chmod +x)

Windows specific: Python not installed

Problem: Running the Libiry installer shows Python not found.

Solution:

IMPORTANT: If you have Python 3.13 or higher, or if you got Python through the Microsoft Store or the new “Python Install Manager” (py), it may not work correctly with Libiry yet. Install Python 3.12 instead.

  1. Install Python 3.12 from python.org
    1. Go to https://www.python.org/downloads/release/python-31210/
    2. Scroll to “Files” at the bottom of the page
    3. Download “Windows installer (64-bit)” -> python-3.12.10-amd64.exe
    4. Run the Python installer
  2. IMPORTANT: on the first screen, check the box “Add Python 3.12 to PATH” before clicking Install Now
  3. Click “Install Now” and wait for it to finish
  4. Click “Close”
  5. Restart your terminal/command prompt
  6. Run python --version to verify

To verify, you can open a Command Prompt and type: python --version It should print: Python 3.12.x

Kivy installation fails

Problem: pip failed to install Kivy

Solution:

# Try installing with base dependencies only
pip install kivy[base]
 
# Or install pre-built wheel
pip install kivy --pre --extra-index-url https://kivy.org/downloads/simple/

PyMuPDF installation fails

Problem: PyMuPDF (fitz) fails to compile

Solution:

Windows: install Visual Studio Build Tools first

Linux:

sudo apt install libmupdf-dev mupdf-tools

No module named ‘kivy’

The venv was not set up correctly. Re-install Libiry.

No runtimes are installed / pymanager error

You have the new Python Install Manager, but no Python runtime. Install Python 3.12 from python.org and re-install Libiry.

The app opens, but then crashes immediately

Delete the venv folder and re-install Libiry.

What is installed exactly?

What gets removed exactly?

UNINSTALL INSTRUCTIONS

can you make a list of everything that might have come onto their computer (python, kivy) and how to remove that again, with terminal instructions? also pointing out the dangers?
● An AppImage install leaves nothing system-level behind — Python and Kivy are bundled inside the AppImage file. The footprint is:

Complete AppImage clean uninstall: rm ~/Downloads/Libiry-*.AppImage rm -rf ~/.config/Libiry/ rm -rf ~/.cache/Libiry/ Leave ~/.kivy/ unless you’re certain you have no other Kivy apps.

install.sh install touches system directories and requires sudo to clean up:

WhatLocationHow to removeDanger
The app │ wherever you put the .AppImage │ rm ~/Downloads/Libiry-*.AppImage │ None │
Settings │ ~/.config/Libiry/ │ rm -rf ~/.config/Libiry/ │ Irreversible — your folder location and customizations are gone │ ├─────────────┼────────────────────────────────┼──────────────────────────────────┼──────────────────────────────────────────────────────────────────────┤ │ Cover cache │ ~/.cache/Libiry/ │ rm -rf ~/.cache/Libiry/ │ Safe — rebuilds itself │ ├─────────────┼────────────────────────────────┼──────────────────────────────────┼──────────────────────────────────────────────────────────────────────┤ │ Kivy config │ ~/.kivy/ │ rm -rf ~/.kivy/ │ Caution — if you have other Kivy apps, this removes their config too │ └─────────────┴────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────────────────────────────────────────┘

| App + Python venv │ /opt/Libiry/ │ sudo rm -rf /opt/Libiry/ │ None beyond losing the app │ |CLI launcher │ /usr/local/bin/libiry │ sudo rm /usr/local/bin/libiry │ None │ |System icon │ /usr/share/pixmaps/libiry.png │ sudo rm /usr/share/pixmaps/libiry.png │ None │ |Desktop entry │ ~/.local/share/applications/Libiry.desktop │ rm ~/.local/share/applications/Libiry.desktop │ None │ |User icon │ ~/.local/share/icons/hicolor/256x256/apps/libiry.png │ rm ~/.local/share/icons/hicolor/256x256/apps/libiry.png │ None │ |Settings │ ~/.config/Libiry/ │ rm -rf ~/.config/Libiry/ │ Irreversible │ |Cover cache │ ~/.cache/Libiry/ │ rm -rf ~/.cache/Libiry/ │ Safe │ |Kivy config │ ~/.kivy/ │ rm -rf ~/.kivy/ │ Caution — other Kivy apps affected │ |System packages │ libsdl2-dev, python3-venv, etc. │ see below │ High danger │ The uninstall.sh script handles everything except system packages and ~/.kivy/.

Do not remove system packages blindly. The packages installed by install.sh (python3-dev, python3-venv, libsdl2-dev, etc.) may be needed by other software. Running: sudo apt-get remove python3-dev python3-venv libsdl2-dev sudo apt-get autoremove could remove dependencies shared with other apps. Only do this if you know these packages were not on your system before installing Libiry.

Application issues

Application won’t start

Problem: Libiry does not start

Solution:

  1. Check if there any Python processes still running on your computer. Close these or restart your computer
  2. Run Libiry_debug.bat instead of Libiry.bat to see error messages
  3. Check if a virtual environment exists in the venv/ folder
  4. Re-run install.bat

Blank window / no books shown

Problem: Libiry opens but shows nothing

Solutions:

  1. Check Settings → Location
  2. Verify the folder contains supported file types
  3. Check the “Only selected file types” setting
  4. Press F5 to refresh

Slow startup

Problem: Libiry takes a long time to start

Solutions:

  1. Large libraries take longer on the first scan
  2. Check your network connection (cover lookup may timeout for slow connections)
  3. Move your library to SSD if on HDD
  4. Reduce your folder depth (fewer nested folders)
  5. Uncheck the ‘Show tags’ box in Settings

Display issues

Covers not showing

Problem: Books are displayed without covers

Solutions:

  1. If the cover field is filled with a URL, check your internet connection (for online lookup)
  2. Verify that your e-books contain embedded covers
  3. Clear the cache
  4. If the cover field is filled with a URL, check if the URL is valid

Text too small/large

Problem: UI elements are wrong size

Solution: Change your font size.

High DPI scaling issues

Problem: The UI looks tiny on a high-resolution display.

Solution: Increase the font size under Settings. Kivy may not auto-scale on all systems.

Book doesn’t open

Problem: Double clicking a book in Libiry doesn’t open it in your default reading app

Solutions:

  1. Check if the book opens correctly in this app outside of Libiry
  2. Some tools (like Obsidian) require a command line interface. Either enable that or change your default markdown app from Obsidian to another app that can read markdown files, like Notepad or the Calibre Viewer. This will not affect your Obsidian experience
  3. Replace Calibre with the Calibre Viewer
  4. Run Libiry in debug mode. It will tell you why it cannot display the file

Tag issues

Calibre tags not displayed in Libiry

Problem: Calibre tags are not visible in Libiry

Solution: There may be a difference in the tags that are shown in Libiry and in Calibre. Calibre stores PDF tags in the subject field, while Libiry uses Keywords.

Tags not saving

Problem: Tags disappear after saving

Solution: Most books require sidecar files. Check if a sidecar file was created next to the book. Ensure write permissions in the folder.

Search issues

Search isn’t finding books

Problem: Books exist, but search doesn’t find them.

Solutions:

  1. Search is case-insensitive but exact by default
  2. Enable Fuzzy search in Settings for partial matches
  3. Search depth is limited to 10 folder levels
  4. Check if files have correct extensions

Fuzzy search too broad

Problem: Fuzzy search returns too many results.

Solution: Disable fuzzy search for more precise matching:

Fuzzy search y/n: N

Performance issues

High memory usage

Problem: Libiry uses too much RAM.

Solutions:

  1. Close other applications
  2. Reduce grid zoom level
  3. Divide large folders into subfolders

Slow scrolling

Problem: Grid scrolling is laggy

Solutions:

  1. Reduce the number of visible tiles (zoom out less)
  2. Make sure that thumbnail cache is working (~/.libiry/cache/)
  3. Use an SSD for library storage

File issues

Permission denied when saving

Problem: Can’t save tags or move files

Solutions:

  1. Check folder permissions
  2. Close files in other applications
  3. Run as administrator (Windows)
  4. Check if files are read-only

Deleted files still showing

Problem: Removed files appear in the grid.

Solution: Refresh the view

Moving files fails

Problem: The move operation doesn’t work

Solutions:

  1. Check if the destination folder exists
  2. Check the write permissions
  3. Make sure that the file isn’t open in another program

Getting help

Debug mode

Run with console output to see error messages:

run_debug.bat

Log files

Check for errors in the console output. No separate log files are created

Reporting issues

When reporting bugs, include:

  1. Operating system and version
  2. Python version
  3. Error message from debug mode
  4. Steps to reproduce
  5. Example files

Report issues at GitHub Issues or at Reddit. Please take into account that I am just one person, doing this free of charge. Not all changes that you request will be granted.

Backlinks