Skip to content

Importing books

MyBibliotheca has separate workflows for book data, reading history, and metadata cleanup. Start with a small file so you can confirm the mapping before importing your full collection.

Choose the right workflow

Workflow Use it for What happens
Direct import Goodreads or StoryGraph library exports Recognizes the format and applies the standard mapping
Advanced import Custom CSV, TSV, or TXT files Shows a preview and lets you map each column
Reading history Session exports containing dates/pages/minutes Matches rows to books and creates reading-log entries
ISBN list One ISBN per row Looks up metadata and creates books when a match is found

Find the import tools from Settings → Data & Import or the Import Books page.

Safe first import

  1. Back up the library.
  2. Export ten or fewer books from your source service.
  3. Open Import Books and upload the file.
  4. Confirm the preview contains the expected columns and rows.
  5. Check the suggested mappings.
  6. Choose the default reading status and media type.
  7. Start the import and inspect the result counts.
  8. Open a few books to verify titles, contributors, covers, dates, ratings, and notes.

Only then import the complete collection.

Goodreads and StoryGraph

Export the library from the source service, then upload the resulting CSV to Import Books. Recognized files receive standard mappings, but the advanced workflow still lets you review and customize them.

Commonly imported data includes:

  • Title, author, additional authors, ISBN, publisher, pages, and publication date
  • Reading status, rating, review/notes, date added, and date read
  • Platform-specific shelves, tags, moods, pace, format, and content warnings
  • Series and other metadata when present in the file or returned by enrichment

Platform tags and shelves are personal metadata. They are not automatically treated as shared genres.

Advanced import

The advanced importer accepts .csv, .tsv, and .txt delimited files. It detects common delimiters such as comma, semicolon, tab, and pipe, then displays the first three rows for inspection.

On the mapping screen you can:

  1. Map each source column to a standard book or personal field.
  2. Leave a column as Don’t Import.
  3. Apply a saved import template.
  4. Create a new global or personal custom field.
  5. Select a default reading status and media type.
  6. Save the mapping as a template for the next export.

Use UTF-8 encoding and keep ISBN columns as text in spreadsheet software so leading zeroes are preserved. Dates are most reliable as YYYY-MM-DD; common Goodreads-style dates are also normalized.

See the complete CSV mapping reference.

What metadata enrichment does

When enrichment is enabled, ISBNs are looked up through the configured providers. Returned information can fill missing titles, contributors, descriptions, publishers, page counts, categories, series data, and covers.

  • A row with a title but no ISBN can still be imported and is marked Needs Review.
  • A row with neither a title nor an ISBN is skipped.
  • An ISBN-only row that cannot be resolved is reported as an error rather than creating a placeholder book.
  • Large imports may take longer or receive partial enrichment because providers can rate-limit requests.

Existing information should not be assumed to be overwritten. Review the result and use metadata repairs for remaining gaps.

Duplicates and reruns

Duplicates are matched by ISBN when available, then by title and author. A duplicate import can merge missing bibliographic information and apply personal reading data to the existing book rather than creating a second global record.

The mapping screen exposes duplicate-handling choices. If your version behaves differently, treat the result counts as authoritative and report the example with the source file and version. Always make a backup before testing a large rerun.

Understanding the result page

The background job reports:

  • Processed: rows examined
  • Success: books created or handled successfully
  • Merged: rows matched to an existing book
  • Errors: rows that could not be imported or enriched
  • Skipped: rows missing usable identifiers
  • Unmatched: rows that require follow-up in workflows such as reading history

Use Download Error Report for row-level diagnostics. Download Failed ISBNs produces a smaller retry list and excludes duplicate-related errors. Correct the source data or wait out provider throttling before trying again.

Imports run in the background. You can leave the progress page and return to the job; cancellation is available while the job is active.

Reading history

Upload a file containing reading dates and metrics such as pages or minutes read. The importer can detect this shape and route it to the reading-history workflow.

The workflow may ask you to match rows to existing books. Resolve unmatched books before finalizing so reading logs are attached to the intended title. A reading-history import creates reading-log entries; it does not replace the book’s bibliographic record.

After importing

  1. Filter the library by Needs Review.
  2. Fix missing ISBNs and covers using Repair metadata.
  3. Check media type and location assignments.
  4. Review a sample of personal dates, ratings, reviews, and tags.
  5. Create another backup after the import is verified.