Libiry

1.7 Troubleshooting

Installation issues

Linux specific: install file is not executable

Problem: Attempting to run the Libiry installer shows that the install file is not executable.

Solution:

Make the install file executable. One of the ways you can do that is:

  1. Open the terminal
  2. Type: ‘chmod +x ’ (with a trailing space)
  3. Drag the install file from your file browser into the terminal window
  4. Press Enter

Windows specific: Python not installed

Problem: Running the Libiry installer shows that Python is 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”
    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.

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 the app in debug mode to check if there are any error messages
  3. Check if a virtual environment exists in the venv/ folder
  4. Re-install the app

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. For markdown files: some tools (like Obsidian) require a command line interface. Either enable that or change your default markdown reading 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 in the settings for more precise matching.

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.

For Windows: click on libiry_debug.bat.

For Linux:

python libiry.py

Log files

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

Reporting issues

When reporting bugs, please 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. As I am just one person, doing this free of charge, it can take some time before your issues are solved. And some issues will never be solved, either by lack of time or by choice.

Backlinks