calibre ebook-convert Command Not Working: How to Fix It

When the calibre ebook-convert command is not working, the cause usually falls into one of four categories: your shell cannot find the program, the command cannot find the input file, the requested conversion is invalid, or the conversion starts but fails on the source book or an option. The fastest solution is to identify which category matches the exact terminal message before changing calibre settings. This guide focuses specifically on the command-line converter, not the Convert books button in the calibre graphical interface.

1. Confirm the Symptom With a Small Safe Test

Start by testing whether your terminal can launch the converter at all. Open a new Command Prompt, PowerShell, Terminal, or Linux shell and run:

ebook-convert --version

If that prints a calibre version, the executable is available in the current shell. Stop changing PATH settings and move to the file and conversion tests below.

If you receive a message such as command not found, ebook-convert is not recognized, or The term 'ebook-convert' is not recognized, the problem occurs before calibre sees your book. Concentrate on the installation location, PATH, and shell sections.

If the command starts but reports missing arguments, that is also useful. It confirms that the shell found the executable. The normal command structure is:

ebook-convert input_file output_file [options]

The input and output must be the first two file arguments. A minimal conversion might look like:

ebook-convert input.epub output.azw3

1.1 Test help before testing a book

Run the following command:

ebook-convert --help

Success means a help page appears. At that point, installation and PATH are working, even if a particular conversion still fails. Do not reinstall calibre merely because a book produces an error.

Options vary according to the input and output formats. To see the options relevant to a particular conversion, include representative filenames before -h:

ebook-convert sample.epub sample.pdf -h

This is more useful than copying an option from an old tutorial because the available input and output options depend on the selected formats.

1.2 Use a simple local file

For the first real test, choose a small, unprotected EPUB, HTML, TXT, or DOCX file that you are authorized to convert. Copy it into a simple local folder with a short name. Avoid a network drive, cloud-synced folder, removable device, and deeply nested path during this test.

Run a conversion without optional switches. For example:

ebook-convert test.epub test.azw3

Success means the command finishes without a fatal error and creates a nonempty test.azw3 file that opens in a compatible reader. Once this works, stop changing installation settings. Any remaining problem is specific to the original file, destination, or options.

2. Check PATH, Installation Location, and the Correct Shell

2.1 Windows

On Windows, first ask the shell whether it can locate the executable:

where.exe ebook-convert

In PowerShell, you can also run:

Get-Command ebook-convert

If neither finds it, locate calibre on the computer. A standard installation commonly places its programs in a Calibre2 folder under Program Files, but you should verify the actual location instead of assuming it. Search for ebook-convert.exe, inspect the target of the calibre shortcut, or open the installation directory from Windows settings.

Once found, test the executable by its full path. In Command Prompt, a typical pattern is:

"C:\Program Files\Calibre2\ebook-convert.exe" --version

In PowerShell, use the call operator before a quoted executable path:

& "C:\Program Files\Calibre2\ebook-convert.exe" --version

If the full path works, calibre is installed correctly and PATH is the issue. Add the directory containing ebook-convert.exe to your user or system PATH, then close every open terminal window and start a new one. Existing shells normally retain the old environment.

Success means where.exe ebook-convert returns the intended executable and ebook-convert --version works without a full path. Stop editing PATH after this result.

2.2 macOS

On macOS, calibre command-line programs are stored inside the application bundle. If calibre is installed in the standard Applications folder, test:

/Applications/calibre.app/Contents/MacOS/ebook-convert --version

If that succeeds, either continue using the full path or add /Applications/calibre.app/Contents/MacOS to your shell PATH. Make the change in the startup file used by your actual shell, such as ~/.zshrc for a typical zsh setup. Then start a new Terminal window and verify:

command -v ebook-convert

Dragging the calibre application to a different folder changes the full path. Adjust the command to match the real application location.

2.3 Linux

On Linux, check the executable selected by the current shell:

command -v ebook-convert

If calibre was installed under /opt/calibre, test:

/opt/calibre/ebook-convert --version

If a full path works but the short command does not, add the installation directory to PATH or create an appropriate link in a directory already on PATH. If the executable exists but fails to start with a missing-library or loader error, preserve that complete message. That is an installation or system-library problem, not an e-book conversion setting.

2.4 Confirm which installation is running

Multiple calibre installations can produce confusing results. The GUI may belong to one installation while the terminal launches an older copy from another directory. Compare these results:

• ebook-convert --version
• where.exe ebook-convert on Windows
• command -v ebook-convert on macOS or Linux

If more than one path appears, call the intended executable by its full path. Success means the expected copy reports its version and performs the test conversion. Remove or reorder obsolete PATH entries only after confirming which installation you want.

3. Check Paths, Extensions, and Command Syntax

3.1 Quote every path containing spaces

Each path containing spaces must be one quoted argument. For example:

ebook-convert "C:\Users\Name\My Books\Source Book.epub" "C:\Users\Name\Converted Books\Source Book.azw3"

On macOS or Linux:

ebook-convert "/Users/name/My Books/Source Book.epub" "/Users/name/Converted Books/Source Book.azw3"

Do not quote the entire command as one argument. Quote the executable separately if its path contains spaces, then quote each book path separately.

Success means the error changes from a missing or unexpected file argument to normal conversion progress. If conversion begins, stop modifying quotation marks.

3.2 Confirm the current directory

A relative path such as input.epub refers to the terminal's current directory, not necessarily the folder shown in calibre. Use dir on Windows or pwd and ls on macOS and Linux to confirm where you are and whether the file is present.

You can avoid this ambiguity by using absolute paths. Also check for hidden or doubled extensions. A file displayed as book.epub in a file manager could actually be named book.epub.zip.

3.3 Give the output file a valid extension

ebook-convert infers the output format from the output filename's extension. For example, output.epub, output.azw3, and output.pdf request different output plugins.

If the output argument has no extension, calibre treats it as a folder for open e-book output rather than guessing a normal e-book format. If you intended to create one EPUB file, specify output.epub.

The input extension must also describe a format calibre can read. Renaming an unrelated or damaged file to .epub does not turn it into a valid EPUB.

3.4 Put options after the two file arguments

The safest order is input file, output file, and then conversion options:

ebook-convert input.epub output.azw3 --title "Corrected Title" --authors "Author Name"

If an option is rejected, run the format-specific help command:

ebook-convert input.epub output.azw3 -h

Confirm the spelling, required value, and whether that option applies to the chosen formats. Success means the command accepts the arguments and starts the conversion.

4. Understand Why the CLI Can Differ From the GUI

The calibre GUI and ebook-convert use the same broader conversion system, but a terminal command does not automatically reproduce every setting you selected in the Convert books dialog. The GUI can use saved conversion preferences, book-specific settings, metadata from the library database, and values entered in the dialog. A basic CLI command primarily receives the source file, output filename, and options explicitly supplied on the command line.

This distinction explains why the GUI may create a book with a particular title, cover, table of contents, page setup, or output profile while the CLI produces different results.

4.1 Reproduce only the setting that matters

Do not add dozens of switches at once. Compare the outputs and identify one meaningful difference. Then consult the relevant help output and add the corresponding option.

• Use metadata options such as --title, --authors, or --cover when the output metadata differs.
• Use --read-metadata-from-opf when you have an OPF file containing the metadata you intend to apply.
• Check page setup and output profile options when layout differs on a particular reader.
• Check table of contents and structure-detection options when chapters are missing or split incorrectly.

If the minimal command works, the converter is not generally broken. Add options one at a time and rerun the same source. Stop when the output matches the required behavior.

4.2 Separate library state from file conversion

ebook-convert converts a file. It does not require you to open a calibre library or select a row in the GUI. Editing metadata in the library database does not necessarily rewrite the original source file you later pass to the terminal.

If you need the library's updated file and metadata, first export or save the intended book format appropriately, then convert that known file. Do not delete or rebuild the calibre library to fix a standalone command that cannot locate an executable or input path.

5. Check Permissions, Security Software, and Source Quality

5.1 Test a writable destination

A conversion can fail when calibre can read the source but cannot create or replace the output. Write the test output to a folder you own, such as a temporary folder inside your user profile. Avoid protected application directories and system folders.

Also make sure the intended output is not open in another program. Some applications or security tools can temporarily lock files. Use a new output filename to distinguish a lock from a conversion problem.

Success means the output appears in the local test folder. If so, the original destination's permissions, locking, or synchronization behavior caused the failure.

5.2 Move the test away from cloud and network folders

Cloud sync clients, network shares, removable media, and managed folders can introduce delayed writes, placeholder files, unusual permissions, or temporary locks. Copy the input to a fully local folder and create the output there.

If the local conversion succeeds, stop changing calibre. Copy the completed output to its final destination afterward, or adjust the external folder's availability and permissions.

5.3 Treat antivirus blocks as evidence, not an invitation to disable protection

If antivirus or endpoint security reports that ebook-convert or a temporary conversion file was blocked, review the product's event history and verify that calibre came from its official source. Do not permanently disable protection as a first troubleshooting step. On a managed computer, ask the administrator to review the exact executable path and alert.

5.4 Test the source file itself

A file can open in one viewer and still contain malformed markup, missing resources, damaged archives, unsupported elements, or misleading extensions. Try converting a second known-good file to the same output format.

• If the second file works, the original source requires inspection or repair.
• If both fail identically, investigate the shared option, output format, installation, or destination.
• If only one output format fails, inspect that output plugin's options and limitations.

This guide does not cover bypassing DRM or removing copy protection. If a file is access-controlled, use an authorized unprotected source or the reading and export methods permitted by its provider.

6. Capture the Full Error and Create Debug Output

6.1 Read stderr, not only the final line

Terminal programs can write normal progress to standard output and errors to standard error, often called stderr. Copy the entire command and complete terminal output, starting with the first warning or traceback. The first specific error is usually more useful than a later summary saying conversion failed.

To save both output streams on many shells, redirect them to a log file. In Command Prompt:

ebook-convert input.epub output.azw3 > conversion.log 2>&1

In common macOS and Linux shells, the same redirection form works:

ebook-convert input.epub output.azw3 > conversion.log 2>&1

PowerShell can combine all streams with:

ebook-convert input.epub output.azw3 *> conversion.log

Success here means the log contains the complete error rather than a cropped screenshot.

6.2 Increase conversion verbosity

Add -v for more detail or -vv for full verbosity:

ebook-convert input.epub output.azw3 -vv

Look for the last named conversion stage, plugin, resource, or file before the failure. Remove passwords, email addresses, personal paths, and book contents before sharing logs publicly.

6.3 Save the conversion pipeline

When conversion starts but the output is malformed or the process fails during a particular stage, use a new empty debug folder:

ebook-convert input.epub output.azw3 -vv --debug-pipeline conversion-debug

The debug pipeline saves intermediate results from different conversion stages. This can show whether bad content came from the input interpretation, document transformation, or output generation. Do not use the folder as a final book, and do not share it if the source is private or copyrighted.

6.4 Use calibre-debug for installation context

If calibre-debug is available, run:

calibre-debug --paths

This reports paths used to set up the calibre environment and can help reveal an unexpected installation. You can also run calibre-debug --version and compare it with ebook-convert --version. Device-detection debugging is useful for USB device problems, but it is not the right first tool when a standalone file conversion fails.

7. Run a Clean Temporary Test Before Reinstalling

Before reinstalling calibre, deleting a library, resetting preferences, or removing plugins, isolate the command with a controlled test:

1. Create a new local folder that is not cloud-synced.
2. Copy in one small, known-good, unprotected source file.
3. Open the correct shell and change to that folder.
4. Run ebook-convert --version.
5. Run a minimal conversion with no optional switches.
6. If it fails, rerun with -vv and save the complete output.
7. If it succeeds, add your original options one at a time.
8. Finally, test the original source and destination separately.

A successful clean conversion proves that the executable and basic conversion engine work. Stop considering a reinstall at that point. The remaining variable is the original command, file, output location, or format-specific option.

Reinstallation becomes reasonable only when the official executable is missing, cannot start by full path, or repeatedly reports missing or damaged program components. Preserve your library and configuration before making broad changes, and avoid deleting a library as a command-line repair step.

8. Quick Fix Checklist

• Run ebook-convert --version to determine whether the shell can find the converter.
• Use where.exe ebook-convert on Windows or command -v ebook-convert on macOS and Linux.
• On macOS, test /Applications/calibre.app/Contents/MacOS/ebook-convert.
• Call the executable by its full path to separate installation problems from PATH problems.
• Open a new terminal after changing PATH.
• Quote every executable or file path containing spaces.
• Use absolute paths when the current directory is uncertain.
• Specify both input and output files before conversion options.
• Give the output filename the extension for the desired format.
• Run ebook-convert input.ext output.ext -h for format-specific options.
• Do not assume GUI conversion settings automatically apply to a CLI command.
• Test a small known-good source in a writable local folder.
• Capture stderr and the complete error text.
• Use -vv and --debug-pipeline when conversion starts but fails.
• Stop changing settings as soon as the minimal test succeeds.

9. Frequently Asked Questions

9.1 Why does calibre work but ebook-convert says command not found?

The graphical application can launch from a shortcut even when its program directory is absent from PATH. Find the actual ebook-convert executable, test it by full path, and then add its directory to PATH if you want to use the short command.

9.2 Why does the full command work in Command Prompt but not PowerShell?

PowerShell handles quoted executable paths differently. When the executable path is quoted, place the call operator before it, as in & "C:\Program Files\Calibre2\ebook-convert.exe" --version. Also compare Get-Command ebook-convert with where.exe ebook-convert to detect aliases or multiple installations.

9.3 Why is my CLI output different from Convert books in the GUI?

The GUI may be using saved preferences, book-specific conversion settings, and metadata stored in the library. Recreate only the required behavior with documented command-line options. Use ebook-convert input.ext output.ext -h to see options relevant to those formats.

9.4 Why does ebook-convert say the input file does not exist?

The shell is probably looking in a different current directory, or an unquoted space split the path into multiple arguments. Verify the filename with dir or ls, check hidden extensions, and retry using a fully quoted absolute path.

9.5 What does success look like?

For a PATH fix, ebook-convert --version works in a newly opened terminal. For a syntax fix, conversion progress begins without a missing-file or unknown-option error. For a complete conversion, the requested output file exists, has a nonzero size, and opens in a compatible viewer. Once the relevant test succeeds, stop modifying unrelated settings.

9.6 Should I reinstall calibre or delete my library?

Not initially. A missing command is usually a PATH or installation-location issue, while a failed conversion is commonly tied to paths, extensions, options, permissions, or the source file. A standalone ebook-convert test does not require deleting the calibre library. Reinstall only after the executable fails when called directly from its verified installation path.