Romance, Historical, Contemporary, Paranormal, Young Adult, Book reviews, industry news, and commentary from a reader's point of view

Goodreads Plugin for Calibre

First off, let me put forward the developer’s caution.  Goodreads allows only a limited number of software calls per minute.  If you make too many, Goodreads might block this.  If you are using this sync for the first time and you have a large library, use the CSV export/import that Goodreads offers.  Don’t worry. I’ll cover doing  big import.

Step 1. Set up your custom columns.

Before you do anything, you will need to create a few custom columns to match Goodreads.

  • Rating -> create a rating column only if you want to override the ratings that are downloaded with the Metadata Lookup feature.*
  • Date Added
  • Date Read
  • Review -> Need a custom column for your reviews or GR will use the “description” from the metadata
  • Tags – > these are equal to your shelves. I call mine GR Shelf.

Step 2.  Customize the Goodreads plugin.

Click on the down arrow on the Goodreads Sync button to access the customize plugin feature.  Here you will authorize the plugin with your account.

customize_syncYour shelves should download. If not, press the blue “Refresh Shelves.” You can also create shelves that will show up on your Goodreads account.  The sync goes both ways. In the lower left, you will map your synchronisable custom columns:

Screen Shot 2013-08-24 at 7.27.26 PM

For each shelf, you need to Edit the “Shelf Add Action” and the “Sync Action”

Sync Action

The sync action step is telling Calibre what to do with the data that it finds at Goodreads.  If you’ve rated a book, added a review, or shelved a book, the sync action can keep your calibre database up to date.  You cannot sync your shelf individually by book. Instead, it syncs by entire shelf. So you’ll sync the Read shelf or the TBR shelf.

Let’s say you  added a book to your “currently-reading” shelf at Goodreads.

Currently reading

Now I want to add that book to my calibre account.  I go to Calibre and select “Sync Shelf”.  Calibre will import that title into my database per the rules I have set.  Go to Customize Plugin on the GR Sync Button. Highlight the Currently Reading shelf.  You want to edit the Sync actions.  For the “currently-reading” shelf, you’d want to add a value to your GR Shelf to read “currently reading”. I also want to add “Date Started” that I included when I added this book to Goodreads.

Once I have this set, I can select Sync Shelf. As you can see by the screenshot, I have three books on my “currently reading” shelf at Goodreads.  In Calibre, I only have one book “linked”.

Sync shelf search linked book

I can create links between my Calibre database and Goodreads by searching my database for the book.  Once I’ve made the link, I hit sync and calibre gives me a warning that it will ignore unlinked books. Great.

Now, my Calibre database and GR shelves have marked “Sweet” in the currently reading category.  But let’s say I have a book in Calibre that I am going to start reading.

Shelf Add Action

This is the action that you are asking Goodreads to take when you Add a Book to the shelf.  Here I am going to add Shannon McKenna’s Fatal Strike to my Currently Reading shelf.  I’ve set my rules as follows.  I want the date started to be set to Today and I want to add “currently-reading” to the GR Shelf.

Screen Shot 2013-08-24 at 6.24.14 PM

Before I enter the command to Add to Shelf, here is my metadata for Fatal Strike  by Shannon McKenna.  The date started is empty as is the GR Shelf.  After the add command, Calibre automatically inserts the date (today) and the “currently-reading” tag.


And when I go to my Goodreads account, you can see I now have four books on my Currently Reading shelf.

currently reading bookshelf

But let’s assume that I’ve read a book now and I want to move it from Currently Reading to Read.  I’m going to use Sweet as my example.   I wrote out a quickie review and gave the rating. I’m not filling out any other information because Calibre will do that for me based on the rules I set.

The Add Shelf actions I have set include

  • Setting the date ended to today
  • Setting the GR Shelf to “Read” (instead of “Currently Reading”)
  • I also check the boxes next to “upload rating, date read, and review text.”

The Sync Actions include:

  • Date Ended = Goodreads Date Read
  • I also check the boxes next to “Sync rating from GR, sync date read, sync review text.”

Here you can see a preview of what is being added to my GR shelf.  The rating is 4 and I have a shorty review along with the date read.

Screen Shot 2013-08-24 at 6.40.12 PM

Automagically, Goodreads is now updated with my review, rating and date read.

Screen Shot 2013-08-24 at 6.41.10 PM

Download tags from shelves/Upload tags as shelves

You can create shelves from Calibre and vice versa by using Download tags from shelves and upload tags as shelves.  Make sure that you’ve a) created a custom tag column for Goodreads shelves and b) that you’ve designated that custom column as the “tags” column in the customize plugin feature.  Remember that you can create custom rules for each shelf.

Screen Shot 2013-08-24 at 7.29.17 PM


This way you can reduce the number of actions to take in order to keep your Calibre database in sync with your Goodreads shelf.  Plus by relying on shelf and sync actions, you can automate several tasks as well.  Remember to update this plugin regularly. Goodreads often changes its code which necessitates users reporting error reports to Kiwidude, the developer, who then fixes the plugin.  You can read more about the Goodreads plugin here at MobileRead.

Step 3.  Mass import using CSV

If you have a huge library and want to sync it to Goodreads, use the mass import feature.  Here are the columns that Calibre accepts and corresponds to fields on the Goodreads site.  You do not have to have all of these filled out because many of them will already exist in Goodreads such as the average rating, publishing, binding, number of pages, year published, etc.

  • Title
  • Author
  • Author l-f
  • Additional Authors
  • ISBN
  • ISBN13
  • My Rating
  • Average Rating
  • Publisher
  • Binding
  • Number of Pages
  • Year Published
  • Original Publication Year
  • Date Read
  • Date Added
  • Bookshelves
  • Bookshelves with positions
  • Exclusive Shelf

To create a CSV file of your calibre database, simply click on the arrow next to the Convert Books button and select Create a catalog of books in your library.  Name your library and then highlight the fields you want to import into Calibre such as title, author, review, my rating, gr_shelf, and any others that would correspond with the GR fields.  Open up your CSV file and make sure that the headers match the GR headers.  The Calibre headers look like this:

Screen Shot 2013-08-24 at 6.57.42 PM

And I need to change them to look like this:

Screen Shot 2013-08-24 at 6.56.43 PM

If you find this plug in helpful, consider donating to the developer.

* Bonus step: Customize Metadata Download sources.

Go to Preferences and select Metadata Download.  Here you will see a list of metadata lookup sources such as Amazon, Goodreads, Barnes & Noble, Fantastic Fiction.  Each Metadata source can be separately configured by highlighting the metadata source and then clicking the green “Configure selected source”

metadata download configure

For instance, let’s assume that you are a heavy Goodreads reader and want to see ONLY the Goodreads ratings.  You would highlight each metadata source that is NOT Goodreads and UNCLICK the rating.  This way only ratings from Goodreads will be downloaded.  You can go through this with each of your metadata sources and customize them. I only like covers from Amazon and Barnes & Noble, for example.  The Goodreads covers are too small for my liking.

Screen Shot 2013-08-24 at 5.12.27 PM

Jane Litte is the founder of Dear Author, a lawyer, and a lover of pencil skirts. She self publishes NA and contemporaries (and publishes with Berkley and Montlake) and spends her downtime reading romances and writing about them. Her TBR pile is much larger than the one shown in the picture and not as pretty. You can reach Jane by email at jane @ dearauthor dot com


  1. Estara Swanberg
    Aug 25, 2013 @ 07:07:57

    Thank you for exploring another useful plugin in detail – I usually get overwhelmed. Is there an option to only sync from Goodreads to Calibre? I don’t want all of the stuff in Calibre to get into GR, personally, but an import of my data and reviews from Calibre makes sense to me, especially as I have no idea how to use the exported .csv file that Goodreads offers.

  2. Meg
    Aug 25, 2013 @ 11:51:50

    Perfect timing! I installed this plug-in last night and was floundering about a bit with it. I did finally managed to get it working, but there’s enough really good tips in here for me to start over and make everything sync correctly. I’ve been trying to remember to use my GoodReads account more so I don’t do things such as buy a book I already owned (as I did when I cracked open Stephanie Laurens’ “The Perfect Lover” last night and realized I had just read it on my Kindle. Oops.)

  3. Sophia (FV)
    Aug 25, 2013 @ 12:10:41

    I’ve been using this plugin for a while and I really like it. You always seem to find a better way to use these tools though. Thanks for sharing.

    And, thank you for the reminder about supporting the developer. I donate to Calibre a couple of times a year, but I forget about the plugin developers. It’s good to support them as well for their hard work and generosity.

  4. Erin Satie
    Aug 25, 2013 @ 12:21:41

    Your last calibre post convinced me to finally collect all my ebooks in one place, with a copy of my own outside the cloud. Took FOREVER & I’m not done yet (I’ve got a handful of books from Barnes & Noble to import).

    So thanks! Because I like Amazon a lot but I’m not sure I trust them.

    But I totally don’t understand the instructions here about how to import my data from Goodreads into Calibre. I have to do the bulk option because I’ve got hundreds of reviews & I was able to make a CSV file, but I have no idea what to do from there, or how that will import info from goodreads.

  5. Jane
    Aug 25, 2013 @ 12:25:17

    @Erin Satie:

    Once you have your CSV file, open it in Excel. Rename the headers so that they match the field names Goodreads uses:

    Author l-f
    Additional Authors
    My Rating
    Average Rating
    Number of Pages
    Year Published
    Original Publication Year
    Date Read
    Date Added
    Bookshelves with positions
    Exclusive Shelf

    Resave (making sure it is still CSV). Then go to this link:

    There you will be given the opportunity to upload your CSV file.

  6. Erin Satie
    Aug 25, 2013 @ 12:50:34

    That seems to export info into goodreads. I’m trying to export info from goodreads.

    Is this possible? I can’t really tell.

  7. Dabney
    Aug 25, 2013 @ 13:27:45

    Is there any way anyone knows of to have books purchased at Amazon automatically download into Goodreads?

  8. Willaful
    Aug 25, 2013 @ 13:39:40

    I’m trying to make the custom columns, but there’s already a “rating” column and it won’t let me use the same name.

  9. Jane
    Aug 25, 2013 @ 15:44:01

    @Erin Satie: Oh sorry. For importing data into Goodreads, use the import plugin.

  10. Estara Swanberg
    Aug 25, 2013 @ 17:07:31

    @Jane: That is a good one for general importing from what I can see from the description and screenshots, but it does not seem to support importing reviews (and all the added, started, finished data). Oh well ^^

  11. Stumbling Over Chaos :: Linkity looking forward to a long weekend
    Aug 30, 2013 @ 08:19:37

    […] Dear Author explains how to use the Goodreads plugin for Calibre. […]

%d bloggers like this: