Skip to content
a cli ebook manager
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


a cli ebook manager built around isbnlib

currently supports epub and pdf

Build Status



python >=3.4 and pip should be fine


from pypi (latest release)

pip install lspace

from github (probably-not-so-stable-dev-stuff)

pip install git+


after installation, you should run

lspace init

this will setup a new configuration file, which you can edit to specify the structure of your library, for example.

a default config file would look like this:

database_path: sqlite:////home/USER/.config/lspace/lspace.db
file_format: '{SHELVE}/{AUTHORS}_{TITLE}'
library_path: ~/library
loglevel: error
default_shelve: misc
default_author: no author
default_language: no language
default_publisher: no publisher

database path

path to your database. the project uses sqlalchemy, so all databases supported by sqlalchemy should be fine.


template string for storing the plain files in the library.

{SHELVE}/{AUTHORS}_{TITLE} would produce files like scifi/cixin-liu_three-body-problem.epub

author and title will be automatically slugified for this.

possible variables to use are: AUTHORS, TITLE, SHELVE, YEAR, LANGUAGE, PUBLISHER

library path

where the imported files are stored


the default python loglevels (debug, info, error, exception)

default_{shelve, author, language, publisher}

the default field names, in case nothing is specified in import



lspace import path/to/ebook.epub

lspace import path/to/folder/*

import from calibre library

lspace import path/to/calibre_library/metadata.db

searching your library

lspace list QUERY [--path]

for example,

lspace list programming --path

would return something like



lspace list dwarf

would return return

Peter Tyson - Getting Started With Dwarf Fortress

removing stuff

lspace remove QUERY

this command will ask you before it actually deletes stuff :)

Peter Tyson - Getting Started With Dwarf Fortress
delete this book from library? [y/N]:

exporting books

lspace export QUERY ~/some/folder/ --format mobi

would convert all books matching on QUERY to 'mobi' and export them to ~/some/folder

to actually export to another format, you need "ebook-convert", which is part of calibre!

setting up a dev env

1. clone this repo

2. make a virtualenv and activate it

virtualenv  env --python=python

source env/bin/activate  # for bash

# or
#. env/bin/  # for fish

3. install requirements

    pip install  -e .[dev]

4. set up a separate config to not mess up your regular installation

# initialize a new config file at a separate path
LSPACE_CONFIG=~/.config/lspace_dev/config.yml lspace init

# change the database and library path! (otherwise it would still use the regular db)
sed -i 's/lspace\/lspace.db/lspace_dev\/lspace.db/g' ~/.config/lspace_dev/config.yml
sed -i 's/~\/library/~\/library_dev/g' ~/.config/lspace_dev/config.yml

# also, if you want, set the loglevel to something else

after this, just set LSPACE_CONFIG to your new config file before you start to try new stuff

export LSPACE_CONFIG=~/.config/lspace_dev/config.yml  # bash
set -gx LSPACE_CONFIG ~/.config/lspace_dev/config.yml  # fish 

why "L-space"?

its named after discworlds library-space dimension :)

You can’t perform that action at this time.