How to Format Files for Self-Publishing on Linux

When I found myself stuck in lockdown in the wrong country, I decided to do what everyone else in my situation would do: write and self-publish a book. So started another chapter of, ‘It seemed like a good idea at the time: the story of my life.’

I use Linux. Specifically, Linux Mint KDE. This usually reduces my computer-related headaches, but it isn’t helpful when I have to deal with companies that expect me to use proprietary software. For example, when I’m trying to format a book. There are myriad self-publishing tutorials floating around the internet, but they’re almost all aimed at PC or Mac users.

Getting my book accepted by Ingram Spark and Kindle Direct Publishing (KDP) was an exercise in trial-and-error, interspersed with periods of banging my head against the nearest wall. I even considered buying a PC. Fortunately, I didn’t stoop to those depths, and I did work out how to make it work.

This article summarises the steps involved. If you just want the TL;DR, scroll to the bottom.

Step 1: Write the manuscript

Contrary to my expectations, this was the easiest part of the whole saga. I like to use Wavemaker so I can work from anywhere, but any word processing program will do the job. About 15 000 words later, I had a usable manuscript.

Step 2: Design the cover

GIMP is my go-to program for playing with graphics. I used paid stock images with an appropriate licence, just to keep it legal. Following suggestions from online tutorials, I kept the dimensions a bit bigger than I thought I’d need. Satisfied with my evening’s work, I moved onto the next step.

Step 3: Turn the manuscript into a properly formatted book

Reedsy’s book editor is a simple tool for writing, editing and formatting simple books. Since my book is mostly words with an occasional picture, it seemed to fit my needs perfectly!

Reedsy is simple and intuitive. Getting my manuscript into their system was straightforward. Uploading my photos and getting them in place was similarly straightforward. The fact that it was going so smoothly should have made me suspicious, but I naively carried on.

Happy with my manuscript, I selected the correct options and downloaded it from Reedsy in both epub and pdf format. That’s where the fun started.

Problem: unzipping zips

When you download a book from Reedsy, each version comes in its own zip archive. You need to extract it to get to your files. The epub zip archive extracted fine, but the pdf zip archive failed repeatedly. After re-downloading it several times with the same result each time, I contacted Reedsy support for help. They were responsive but unable to work out the problem. After some back-and-forth, they just sent me the pdf directly.

That was fine, until I needed to tweak it and the problem started again.

Solution: revert to the command line

I eventually found a solution: extracting the pdf zip archive from the graphical user interface (GUI) fails, but extracting it works fine from the command line.

Use ‘unzip’ in the command line.

One day I’ll learn why the epub archive extracted fine from the GUI and the pdf archive didn’t, but for now I’ll move on.

Step 4: Upload files to Ingram Spark

After extensive research (ie. twenty minutes browsing self-publishing blogs) I decided to publish on Ingram Spark and Kindle Direct Publishing. First stop, Ingram Spark.

Getting started is straightforward, and Ingram Spark has clear explanations for each step. Setting up an account and preparing to upload a book is very simple. I got all the way to ‘Upload your files’ before I ground to a halt.

Problem: Ingram Spark infinite loop

When I tried to upload my files, I found myself stuck in a loop. At the end of the setup screens, I got the error message:

‘Account setup incomplete, Since you have not completed your account setup, you are not able to upload files at this time. Please take a moment to finish setting up your account.’

Clicking on the ‘Finish account setup’ button took me to a page saying:

‘Congratulations! Your account is complete.’

Going back to the ‘Upload files’ page gave me the same error message.

Solution: switch to Ingram Spark beta

Ingram Spark support answered my enquiry fairly promptly, but it took them three days to tell me how to fix it.

Apparently, I’d enrolled in the beta version then somehow switched back to the standard version. Switching back to the beta version allowed me to upload my files and progress to the next problem.

Problem: Files rejected by Ingram Spark

With some relief, I uploaded my files. They all triggered errors.

The error message for my print-ready pdf suggested one of my photos was less than 200dpi. That seemed odd, given that all of my photos were uploaded at 400–600dpi.

I spent two days messing around with photos, double-checking resolutions and sizes, and re-uploading them before I eventually gave up.

The epub triggered the error:

‘ERROR]OEBPS/31_about-the-author.xhtml: This file should declare in the OPF the property: svg.’

I’m neither an IT expert nor a design expert, but I do know the difference between different file formats. I was certain that all my images were pngs, not svgs. After confirming this, I contacted Reedsy support, and heard nothing back.

Solution: give up and try something else

I checked my epub with Epub Validator, which found no problems. After several failed attempts at editing the epub directly using Sigil and Calibre (both fantastic programs, by the way), I gave up.

Step 5: Transfer manuscript into Scrivener for Linux

Scrivener is a brilliant word-processing program and outliner designed for authors. When they stopped maintaining the Linux version, they were kind enough to release the final Linux version for free, and it still works brilliantly.

I downloaded my manuscript from Reedsy in docx format. It only took a few hours to import it into Scrivener and tidy it up.

Exporting it as a pdf worked flawlessly, and Ingram Spark accepted the generated file with no further complaints.

Problem: epub Table of Contents

Exporting as epub was more entertaining. The file was fine, but the generated Table of Contents was awful, and I couldn’t find any way to exclude it. After tweaking settings and exporting it over fifty times, I gave up.

Solution: edit Table of Contents in Sigil

I generated the epub in Scrivener, opened it in Sigil, and edited the Table of Contents directly. Ingram Spark accepted the file.

With a (premature) sigh of relief, I moved on to step 5.

Step 6: Upload hard-copy book cover

Ingram Spark has a helpful book cover template generator that you can use to ensure your book cover is the right dimensions. All you have to do is enter your ISBN, trim size and a few other details, and they’ll send you a pdf or InDesign template.

Problem: I need an ISBN to generate a template

I’d completely forgotten about the ISBN. Doh!

Solution: apply for an ISBN

Fortunately, the National Library of New Zealand was very prompt: I applied on a Friday, I received my ISBNs on Tuesday. Given that the country is in lockdown, I was impressed.

I downloaded my book cover template, then ground to a halt. I had no idea how to use a pdf template.

Problem: I don’t know how to use a pdf book cover template

Google wasn’t helpful: the bulk of the resources are aimed at InDesign, which is out of my price range and won’t run on Linux.

Solution: GIMP can import pdfs

GIMP will import pdfs, so I started there. After a fair bit of fiddling with layers, I managed to get everything manually lined up on the template and exported as pdf.

Problem: GIMP won’t generate pdfs with CMYK colour profiles

Heart in mouth, I tried to upload my new cover pdf. Ingram Spark rejected it. Apparently, there are different colour profiles, and GIMP uses the wrong one.

I was a hair’s breadth from just giving up and just paying someone to format it properly, when I came across Scribus.

Scribus is an open-source cross-platform desktop publishing program. If, like me, you’re clueless about desktop publishing, it’s got a very steep learning curve. However, it will generate a cover that’s acceptable to Ingram Spark.

I was still floundering when I came across these posts:

They do a fabulous job of explaining, step-by-step, at absolute-beginner-level, how to use a template to generate a cover in Scribus.

Solution: use Scribus to generate the pdf

Generate the basic graphics with GIMP, export as png, and import that into Scribus to generate the pdf.

Ingram Spark finally accepted my cover. I breathed a sigh of relief and gave myself the weekend off before the next step.

Step 7: Upload to Kindle Direct Publishing

I naively assumed that the files I used for Ingram Spark would work for Kindle Direct Publishing. They don’t.

Problem: pdf formatting is different on KDP

For some reason, the margins were completely different when I uploaded my pdf to KDP. It failed the auto-check because a few lines ran into the margins.

Solution: reformat the pdf

This was when Scrivener shone: tweaking margins and line breaks was straightforward. At this point, I started saving a separate Scrivener project for each version of my book on each platform.

Problem: book cover dimensions are different on KDP

It would be too much to hope that, just because the book is the same size on KDP as on Ingram Spark, the book cover template would be the same. At least this time I already had a system for using pdf templates, so it didn’t take too long to adjust my cover.

Solution: recreate the book cover

Use Scribus and GIMP to regenerate my book cover to fit the KDP template. Save files for each version and platform separately to make it easier next time.

Problem: KDP couldn’t detect my bar code

Although my cover had a perfectly functional bar code, KDP couldn’t detect it.

Solution: recreate the book cover without a bar code

Go back to GIMP and Scribus, and generate a cover version without a bar code. KDP can generate their own bar code and put it on the cover.

Step 8: Celebrate! And tidy up my notes for next time

All of my files were finally accepted, my proof copy was fine, and I now know what I need to do for next time. You can find my book The Merchant Navy Survival Guide on Amazon.

To summarise my future workflow:

  1. Write the manuscript directly in Scrivener;
  2. Design the cover in GIMP, and save all layers in GIMP’s default format (xcf) so that I can edit it easily;
  3. When I find the perfect settings to compile each version in Scrivener, save each project separately. That means I have separate projects for Ingram Spark paperback, Ingram Spark ebook, KDP paperback and KDP ebook;
  4. Order an ISBN before I start messing around with book cover templates; and
  5. Use GIMP and Scribus to generate compatible files for book covers.

So, what’s next?

I’ve just started working through the system to make my book available on Google Books. How hard can it be? I guess I’ll find out next week.

6 thoughts on “How to Format Files for Self-Publishing on Linux

Add yours

  1. “…considered buying a PC.”
    Don’t do it! 🙂
    Hey, I slacked and grabbed a version of Puppy Linux, which is too for self-publishing, but I was tired, so I feel your pain. Thank you for this Linux-user self-pub. Man page!
    Stay safe,

    Liked by 1 person

  2. May I simply just say what a relief to find someone that actually knows what they’re discussing on the web. You certainly know how to bring a problem to light and make it important. More and more people need to read this and understand this side of the story. I was surprised that you are not more popular because you definitely have the gift.


  3. Most of the things you state happens to be astonishingly appropriate and it makes me wonder the reason why I had not looked at this in this light before. This article really did switch the light on for me personally as far as this particular issue goes. However there is one particular point I am not necessarily too comfortable with so while I try to reconcile that with the actual central idea of the point, permit me see exactly what all the rest of your visitors have to point out.Very well done.


  4. Hmm is anyone else having problems with the images on this blog loading? I’m trying to determine if its a problem on my end or if it’s the blog. Any responses would be greatly appreciated.


    1. I’ve just tried it on my phone and a browser I’m not logged into, and it works for me. If anyone else is having trouble, I can try it from other devices and see if I can nail down a problem :/


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a website or blog at

Up ↑

%d bloggers like this: