Importing Your Books from StoryGraph
If you've been tracking your reading on StoryGraph, you can bring your books, ratings, and reading history into Book Assembly. This guide walks you through the entire process.
What You Can Import
When you import from StoryGraph, the following information comes across:
- Book details - Title, author(s), ISBN
- Your ratings - Quarter-star ratings (1.25, 3.25, etc.) rounded to the nearest half-star
- Your reviews - Written reviews (HTML tags are automatically stripped)
- Reading status - Whether you've read, are currently reading, want to read, or did not finish each book
- Reading dates - Start and finish dates, including re-reads
- Your tags - Custom tags become lists in Book Assembly
- Moods - StoryGraph mood tags (adventurous, dark, funny, etc.)
- Pace - Reading pace (slow, medium, fast)
- Content warnings - With severity levels stripped, matched to predefined warnings
- Ownership - Whether you own the book
- Format - Paperback, Hardcover, Audio, Digital
What Doesn't Get Imported
Some information isn't included in StoryGraph's export:
- Page count, publisher, publication year - StoryGraph doesn't export these
- Genres - Not included in StoryGraph exports despite being a core feature
- Private notes - Not included in the export
- Character trait ratings - StoryGraph-specific features like "Character-driven" and "Strong development"
- Content warning severity levels - Graphic/Moderate/Minor levels are stripped on import
- Series information - Not included in the export
Before You Start
You'll need to export your library from StoryGraph as a CSV file. Here's how:
- Go to StoryGraph (opens in new tab) and sign in
- Go to Profile > Manage Account > Manage Your Data
- Click Export StoryGraph Library
- Important: The CSV file is emailed to you - it's not an instant download like Goodreads
- Check your email (including spam) for the download link
- Download the CSV file to your computer
The download link in the email expires after 30 days, so don't wait too long to download it.
The Import Process
Step 1: Upload Your File
Once you have your CSV file:
- Go to Dashboard > Data in Book Assembly, then open the Import tab
- Click Import from StoryGraph
- Click Select CSV File or drag and drop your file
Book Assembly will read your file and show you what it found. This doesn't import anything yet - you're just previewing.
Step 2: Select Books to Import
After uploading, you'll see a list of all the books found in your export. Each book has a checkbox to include or exclude it from the import.
What the columns mean:
- # - Row number, helpful for finding specific books
- Checkbox - Tick to include this book, untick to skip it
- Title - The book's title as it appears in StoryGraph
- Author - The author(s) of the book
- Rating - Your star rating, or a dash if you haven't rated it
- Status - Read, Reading (currently reading), TBR (to be read), or DNF (did not finish)
Filtering and searching:
Use the search box to find specific books by title or author. You can also filter by:
- Status - Show only read books, currently reading, to-read, or DNF
- Tag - Show only books with a particular StoryGraph tag
The checkbox in the header selects or deselects all currently visible books. This is useful for bulk selections after filtering.
Understanding "selected for import":
The count at the top (e.g., "45 of 53 books selected for import") shows how many books will actually be imported. Books you've unticked won't be imported.
Step 3: Map Your Tags
StoryGraph has "tags" for organising books. Book Assembly has "lists" which work similarly. In this step, you decide what happens to each tag:
For each tag, you can choose:
- Skip - Don't create a list; books with this tag are still imported, just not added to any list
- Create new list - A new list with the same name will be created
- Use existing list - If you already have a list with a similar name, you can add books to it
About StoryGraph tags:
Tags in StoryGraph are lowercase and hyphenated (e.g., "another-custom-tag", "dystopian"). You can rename them to something friendlier when creating new lists in Book Assembly.
Step 4: Match Authors
If you already have books in your library, this step helps keep author names consistent. For example, if your existing library has "J.R.R. Tolkien" but StoryGraph uses "J. R. R. Tolkien", you can choose which spelling to use.
For each author variation, you can:
- Keep as imported - Use the name exactly as it appears in StoryGraph
- Use existing - Match to an author name already in your library
This keeps your library tidy and makes it easier to browse by author later.
Step 5: Import
Once you're happy with your selections, click the import button. Your books are imported in the background - you can navigate away and use Book Assembly while it processes.
What happens:
- Books are added to your library in the background
- Duplicate books (ones you already have) are automatically skipped
- New lists are created as needed
- Content warnings are matched to predefined warnings, and unmatched ones are created as custom warnings
- Author names are updated based on your choices
- Cover images are looked up from online databases (if enabled)
- You'll receive an email summary when the import is finished
Cover images
If enabled, covers are looked up after your books are imported. A few things to keep in mind:
- Covers are found by ISBN when available, or by title and author as a fallback
- StoryGraph doesn't always export ISBNs reliably, so some books may not find covers automatically
- The covers found may not match your exact edition - they come from public databases
- Any book without a cover can have one added later from its edit page
Understanding Reading Status
Book Assembly tracks your reading in a slightly different way to StoryGraph:
| StoryGraph | Book Assembly | What it means |
|---|---|---|
| read | Finished | You've completed the book |
| currently-reading | Reading | You're partway through |
| to-read | TBR | On your list to read |
| did-not-finish | DNF | You started but won't finish |
Note: StoryGraph has native DNF support (unlike Goodreads which needs a custom shelf), so all your DNF books are detected automatically.
Handling Duplicates
Book Assembly automatically detects books you already have to help prevent duplicates. It checks:
- ISBN - The unique book identifier (most reliable)
- Title + Author - As a fallback when ISBN isn't available
Books detected as duplicates are marked with a "Duplicate" badge and automatically deselected. However, if you want to import a duplicate anyway (for example, if it's a false positive or you want a separate entry), you can select it manually and it will be imported.
Moods and Pace
StoryGraph moods map directly to Book Assembly's predefined moods: adventurous, challenging, dark, emotional, funny, hopeful, informative, inspiring, lighthearted, mysterious, reflective, relaxing, sad, and tense. Any moods that don't match the predefined list are stored as custom moods.
Pace (slow, medium, fast) maps directly across and is preserved during import.
Content Warnings
StoryGraph exports content warnings in a severity format such as "Graphic: X, Y; Moderate: Z; Minor: W;". During import, Book Assembly strips the severity levels and matches each individual warning to its predefined list of content warnings.
Warnings that don't match a predefined warning become custom content warnings. The Content Warning Description field from StoryGraph maps to the freetext notes on the book.
You can review and edit content warnings after import from each book's edit page.
Quarter-Star Ratings
StoryGraph uses quarter-star increments (1.25, 3.25, 4.75, etc.). Book Assembly supports half-star increments. During import, ratings are rounded to the nearest 0.5 - for example, 1.25 becomes 1.5 and 3.25 becomes 3.5.
Books Read Multiple Times
If you've read a book more than once (indicated by multiple date ranges in "Dates Read"), Book Assembly creates separate reading entries for each, preserving start and finish dates. They're stored in chronological order.
Import Limits
Books per import: Book Assembly imports up to 1,000 books at a time. This helps keep the import process fast and reliable.
If you have more than 1,000 books:Don't worry! You can import your library in batches:
- Import your StoryGraph file as normal - the first 1,000 books will be imported
- After the first import completes, import the same file again
- Book Assembly automatically skips books you've already imported (using ISBN and title matching)
- Repeat until all your books are imported
This typically only takes 2-3 imports even for very large libraries, since duplicates are skipped quickly.
File size: The maximum file size is 50MB. A typical StoryGraph library is usually well within this limit.
Tips for a Smooth Import
- Check your email - The export file is emailed to you, not downloaded instantly. Check your spam folder if you don't see it
- Review before importing - Take time to look through the book list and unselect any you don't want
- Check tag mappings - Make sure your important tags are being handled correctly
- Don't worry about missing metadata - Page count, publisher, and publication year aren't in StoryGraph exports, but you can add them later
- Large libraries - If you have over 1,000 books, plan to do 2-3 import batches (duplicates are auto-skipped)
If Something Goes Wrong
File won't upload:
- Make sure it's the CSV file from the StoryGraph email (not a screenshot or PDF)
- Check the file isn't larger than 50MB
- Try requesting a fresh export from StoryGraph
Books are missing:
- They may have been filtered out - try resetting the filters
- They may have been detected as duplicates
- Check if they were unchecked before import
Wrong reading status:
- You can edit individual books after import to correct their status
Missing covers:
- StoryGraph ISBNs are not always reliable, so some books may not find covers automatically
- You can add covers manually from each book's edit page
Content warnings not matching:
- Check the content warnings section in the book edit page to review and adjust
After Importing
Once your books are imported, you can:
- Add or change covers - If you skipped cover lookup, or want a different cover, you can add covers from each book's edit page
- Organise into series - StoryGraph doesn't export series information, so you'll need to group related books together manually
- Add page count, publisher, and publication year - These aren't included in StoryGraph exports
- Add genres - Genres aren't included in StoryGraph exports despite being a core feature
- Edit details - Fix any information that didn't import correctly
Your StoryGraph account is completely unaffected by this process. You can continue using StoryGraph alongside Book Assembly, or transition fully - it's up to you.