# Import from Calibre

> Bring your Calibre library into Boeks, with its details, ratings, read status, highlights, and where you were, and see what changes on the way.

Canonical: https://boeks.app/docs/guides/import-from-calibre

Boeks imports a Calibre library in one step: its EPUBs and audiobooks, with the details you gave them in Calibre, your ratings and read status, the highlights you made in Calibre's viewer, and where you were in each book. Your Calibre library is only read, never changed, so you can keep using it.

## Start a library from Calibre

When you first open Boeks, choose a folder for your Boeks library, as in [Set up your library](/docs/guides/set-up-your-library). In the empty library, choose **Import From… › Calibre…** and pick your Calibre library's folder: the one with `metadata.db` in it, usually `Calibre Library` in your home folder. Boeks shows what it'll bring over and what it changes on the way, and **Import** starts it. You can hide its progress and keep reading, or stop it: the books already imported stay.

If your library already has books, choose **File › Import From › Calibre…** on a Mac, or **+ › Import From › Calibre…** on iPhone and iPad.

## What comes over

- **EPUBs and audiobooks.** A book with both becomes one book with two editions. Books with only other formats, such as MOBI or PDF, stay in Calibre.
- **Details.** Titles, authors, series, identifiers, publishers, dates, and descriptions are written into the copied files where Calibre's differ from them, and subtitles from a **Subtitle** column. Tags become genres, as Calibre writes them into files.
- **Covers,** when Calibre's is another picture than the file's.
- **Ratings.** Boeks rates in whole stars, so half stars are rounded up: 3½ stars become 4.
- **Read status,** from the columns you made for it in Calibre (below).
- **Highlights and notes** from Calibre's viewer, found in each book by their text, with their colors and dates.
- **Where you were,** from Calibre's viewer or your Kobo, whichever was later, and **time spent reading** from the Kobo Utilities plugin.

Books you imported before are skipped, so importing again adds only what's new.

## Books already in your library

A book you already have in Boeks, from another app or added as a file, isn't added again. Its highlights, read status, rating, and where you were in Calibre come into the book you have, and its own details and file stay. Boeks lists these books before importing: turn off any that aren't the same book, such as another translation, and they're left out.

## Read status

Calibre has no read status of its own, so many people add a column for it, and the Kobo Utilities plugin adds its own. Boeks takes Kobo Utilities' columns from its settings, and looks for the others by their names:

- a column of values, such as **Status** (`#status`) with Read, Reading, and To read
- a yes-or-no column, such as **Read** (`#read`)
- how far you've read, such as Kobo Utilities' **Percent Read** (`#percent_read`): a book at 100% is read, and one you've started is being read
- when you finished, such as **Date Read** (`#date_read`)
- when you last read it, such as Kobo Utilities' **Last Read** (`#last_read`), which dates your reading but doesn't make a book read

Your read books keep the dates you finished them, so they sort and count as they should. Before importing, you can pick other columns, or none, including the one for subtitles. Kobo Utilities' time spent reading comes over as a total for each book, as the Kobo only counts that. Boeks knows the usual values, such as Finished, Currently reading, DNF, and To read. For any it doesn't know, it lists them and asks what they mean; books with a value you leave are imported without a status.

## What doesn't come over

- **Bookmarks.** Calibre keeps only a position for them, not their text, which Boeks needs to find them.
- **Highlights whose text has changed,** as when the book was converted or edited after you highlighted it.
- **Custom columns** other than those for read status, and Calibre's other settings.

When the import is done, Boeks lists what it changed on the way and anything it couldn't bring over.

## Books already on your Kobo

If Calibre put your books on your Kobo, Boeks knows them there. Calibre keeps a list of the books it sent on the Kobo, with its own ID for each, and Boeks keeps the same ID for every book it imports. When you sync your Kobo:

- **Calibre's copies stay.** Boeks doesn't send a second copy of a book Calibre already put there, even when the names differ, as for a book with several authors.
- **Your reading comes back.** Finishing a book, your highlights and notes, and where you are in Calibre's copy come into Boeks, as for books Boeks sent.
- **Calibre's copies stay Calibre's.** Boeks never changes or removes them, so a new title or cover you give a book in Boeks doesn't reach that copy.
- **Books it can't match are listed.** The sync says how many books on the Kobo from Calibre it didn't find in your library: books you didn't import, or that are in your library without Calibre's ID, such as ones you added as files. Those may end up on your Kobo twice.

Import from Calibre before you first sync your Kobo with Boeks, so Boeks knows Calibre's copies from the start.

## From the terminal

The `boeks` command imports a Calibre library too:

```sh
boeks import ~/"Calibre Library"
```

Add `--dry-run` to see what it would bring over first, with the books already in your library and their Calibre IDs: `--leave-out` and an ID leaves one out. `--status-column`, `--read-column`, `--percent-read-column`, `--date-read-column`, `--last-read-column`, `--location-column`, `--time-spent-column`, and `--subtitle-column` choose the columns, and `--status-value 'Someday=unread'` says what a value means.
