Calibre ebook-meta Command Not Changing Metadata: How to Fix It

The ebook-meta command can appear to run successfully while the expected title, author, cover, series, or other metadata still looks unchanged in calibre or on an e-reader. In most cases, the command is not updating the place you are checking. ebook-meta writes supported metadata directly to an e-book file, while calibre normally displays metadata stored separately in its library database. Device libraries may maintain another metadata cache of their own. Other common causes include editing the wrong copy, using a format or field that cannot be written, failing to quote a path, or sending an older copy to the device. The following steps isolate these possibilities without risking your main library.

1. Confirm the Symptom With a Small Safe Test

Start with a copied file outside your calibre library. Do not experiment on the only copy of a book or directly modify files inside a calibre library folder. calibre manages the files and folders in its library, so manual changes there can create confusing results.

1.1 Create a disposable test file

Copy one non-protected EPUB to a temporary folder such as C:\CalibreTest on Windows or ~/CalibreTest on macOS and Linux. EPUB is useful for this test because it supports writing common metadata fields.

Run a simple command that changes the title to a distinctive value:

ebook-meta "C:\CalibreTest\test.epub" --title "Metadata Test 123"

On macOS, the command-line tools may need to be called from inside the calibre application bundle:

/Applications/calibre.app/Contents/MacOS/ebook-meta "$HOME/CalibreTest/test.epub" --title "Metadata Test 123"

On Linux, a typical command is:

ebook-meta "$HOME/CalibreTest/test.epub" --title "Metadata Test 123"

Paths and values containing spaces must be enclosed in quotation marks. If your shell cannot find ebook-meta, use the full path to the command installed with calibre.

1.2 Read the same file back immediately

Do not open calibre yet. Ask ebook-meta to read the exact file you just changed:

ebook-meta "C:\CalibreTest\test.epub"

Success means the output now reports Metadata Test 123 as the title. At that point, stop changing command-line options. The file was updated, and any remaining mismatch is probably in calibre's database, the copy sent to the device, or the device's own cache.

If the old title is still reported, confirm the full path, file extension, modification time, and command syntax. Also verify that you edited the copied test file rather than another file with the same name.

1.3 Check the output file directly

Use the operating system's file information to see whether the modification time changed. You can also copy the edited file into a second empty folder and read it again with ebook-meta. This prevents shortcuts, recent-file lists, and duplicate filenames from directing you to another copy.

The calibre E-book viewer is useful for checking the book's content, but its window title or library launch behavior is not always a definitive test of the metadata embedded in the file. The command's readback output is the cleaner first check.

2. Understand File Metadata Versus Calibre Library Metadata

The most important distinction is that ebook-meta edits metadata inside an e-book file. It does not automatically update the corresponding book record in calibre's library database. calibre's main book list is built from the library database, not by rereading every book file whenever the program starts.

2.1 Why calibre still shows the old title or author

When a book is added, calibre reads available information and creates a database record. If you later run ebook-meta against an EPUB, PDF, or another supported file, that operation changes the file but not the existing database record. Restarting calibre usually does not import the embedded values automatically.

If your goal is to change what the calibre library displays, use one of these methods:

• Open the book's Edit metadata dialog and change the fields directly.
• Use the Edit metadata dialog's format-management controls to read metadata from a selected format.
• Use calibredb set_metadata when you specifically need command-line access to the calibre database.

Success means the updated value appears in calibre's book list and Edit metadata dialog. Once it does, stop rerunning ebook-meta, because the library database was the actual target.

2.2 When to use the GUI metadata editor

The GUI is the safest choice when you want calibre itself to show the change, use the new values during conversion, or send corrected information to a device. Select the book, press E, make the change, and save it. For an existing format whose embedded metadata is already correct, open Edit metadata, locate the available formats, and use the option that reads metadata from the selected format into the book record.

Be careful when importing from a format because it can replace several fields, not only the one you intended to fix. Review the resulting title, authors, identifiers, language, series, and cover before continuing.

2.3 Re-add or update the format instead of creating duplicates

If you edited a copy outside the library and want that exact file to replace the library's existing format, select the correct book record and use Add files to selected book records. You can also drag the file onto the selected book's details panel. This updates or adds a format to the existing logical book.

Using the main Add books action may create a second book record instead. If that happens, you can end up viewing the old record while the corrected file belongs to the new one. Success means the intended record contains the corrected format and no unnecessary duplicate record was created.

2.4 Use the database command for database metadata

calibredb, rather than ebook-meta, is calibre's command-line interface to its library database. For example, after identifying the correct book ID, a field can be changed with a command shaped like this:

calibredb set_metadata BOOK_ID --field "title:Metadata Test 123" --library-path "PATH_TO_LIBRARY"

Work against the correct library path, especially if you maintain multiple libraries or use the Content server. Confirm the result with calibredb show_metadata BOOK_ID or by opening the book in calibre. Do not manipulate metadata.db directly.

3. Check Format Support and Command-Line Options

ebook-meta can read metadata from more formats than it can write. In addition, individual formats do not necessarily support every metadata field. calibre's documentation warns that an unsupported metadata change can be silently ignored, which closely matches the symptom of a command apparently completing without changing the result.

3.1 Verify that the format supports writing

Common writable formats listed in calibre's command documentation include EPUB, KEPUB, AZW3, MOBI, PDF, DOCX, FB2, ODT, RTF, and several others. Formats such as archive or comic-book containers may be readable without offering equivalent metadata-writing support.

Run ebook-meta --help on your installed copy and compare your file extension with its supported writing formats. If the format is not writable, use a supported output format where appropriate or manage the information in calibre's database. Do not assume a readable format is also writable.

3.2 Test one widely supported field

Different formats support different fields. A format might accept a title and author while ignoring series information, ratings, tags, or a cover. Test a basic field first:

ebook-meta "book.epub" --title "Temporary Test Title"

If the title works but another field does not, the command and file access are functioning. The remaining issue is likely a field limitation, field syntax, or device display limitation. Stop changing permissions or reinstalling calibre at this point.

3.3 Check quoting and shell-specific characters

Quote paths, titles, and other values containing spaces. Authors are separated with an ampersand in the --authors value, but an ampersand can also have a special meaning to the shell. Quote the entire value:

ebook-meta "book.epub" --authors "First Author & Second Author"

Verify dates, identifiers, ratings, tags, languages, and series indexes against the syntax shown by ebook-meta --help. If a complex command fails, remove all optional arguments and add them back one at a time.

3.4 Confirm you are running the expected executable

Computers with multiple calibre installations may expose an older or different ebook-meta executable through the command search path. Run:

ebook-meta --version

Then locate the executable with where ebook-meta on Windows or which ebook-meta on macOS and Linux. This is not an instruction to chase a particular version number. It simply verifies that the command belongs to the calibre installation you expect to use.

4. Check Conversion, Devices, Plugboards, and Cached Metadata

A successful file edit does not guarantee that a converted output or previously transferred device copy will change. Each stage may create or retain another copy with its own metadata.

4.1 Confirm which file was converted

If you edited an EPUB but then converted an older library copy, the output will inherit metadata from the book record and conversion process rather than from the external file you tested. Replace or add the corrected source format to the intended library record before converting.

After conversion, save the output format to a temporary folder and inspect that exact output with ebook-meta. Success means the converted file reports the intended fields. If it does, stop changing conversion settings and move to the device checks.

4.2 Inspect metadata plugboards

Metadata plugboards can deliberately alter selected metadata fields when a book is saved to disk or sent to a device. A plugboard may therefore replace the title or author you embedded with ebook-meta.

Review the metadata plugboard settings under calibre's import and export preferences. Check the combination of output format and target device, because plugboards can be specific to both. Temporarily disable only the relevant plugboard and send a disposable test book again.

Success means the newly transferred copy displays the expected metadata. You can then correct the plugboard template or leave it disabled. Do not disable unrelated plugins or settings.

4.3 Remove the old device copy before resending

Many readers maintain an internal catalog or database. Copying a revised file over an existing filename may not force that catalog to refresh. In calibre's device view, remove the old device copy, eject the device safely, let the reader update its library, reconnect it, and send the corrected book again.

If the device still shows the old entry, use a temporary distinctive title and, where practical, a different filename. This helps determine whether the reader is matching the new file to an old database record.

Success means the device displays the temporary title after processing the newly transferred file. Restore the desired title afterward and repeat only the confirmed transfer process.

4.4 Account for reader limitations

Some devices ignore certain embedded fields, derive display information from filenames, or keep title and author data in a separate catalog. Some metadata, such as comments or descriptions, may not be displayed by the reader at all. A field that is present when read directly from the file can still be absent from the device interface.

When direct file inspection shows the new value but the device does not, consult the device's supported metadata behavior. At that point, the evidence does not indicate that ebook-meta is failing.

4.5 Check Content server and emailed copies

The Content server presents data associated with the selected calibre library. Editing an unrelated external file will not update that library record. Confirm that the server is exposing the same library you edited and refresh the client page or application after updating the database.

Likewise, emailing or sharing a book creates another copy. Confirm that you attached the corrected output rather than an older file from a downloads folder, previous export, or email attachment cache. Email account settings do not affect whether ebook-meta can write to a local file, so investigate them only when the local readback is correct and the delivered attachment is wrong.

5. Check File Access, USB Mode, Security Software, and Storage

Operating system and storage problems matter when ebook-meta cannot replace the file or when the corrected copy never reaches the intended destination.

5.1 Test in a normal local folder

Move a copy to a user-writable local folder rather than editing it on a device, network share, cloud-synchronized folder, read-only medium, or protected application directory. Close programs that may have the file open, then run the small title test again.

On Windows, check the file's Properties dialog for a read-only state and confirm that your account can modify the containing folder. On macOS and Linux, inspect file ownership and permissions. Avoid solving a narrow permissions problem by running every calibre command as an administrator or root user, because that can create files your normal account cannot later manage.

Success means the local copy's modification time changes and ebook-meta reads back the new title.

5.2 Pause cloud synchronization during the test

Cloud-sync tools can upload, restore, lock, or duplicate a file while it is being replaced. Pause synchronization briefly, copy the test book into a non-synced local folder, and repeat the operation. If this works, resume synchronization only after closing the file and confirming the final result.

A calibre library should not be concurrently modified from multiple computers. If your library is stored in a synchronized location, make sure no other calibre process or computer is accessing it during troubleshooting.

5.3 Avoid editing files directly over USB

A reader connected in an unsuitable USB mode may not expose normal writable storage. Even with mass-storage access, editing the device file in place makes it harder to distinguish a write problem from a reader-cache problem.

Edit and verify the file locally first. Then transfer it through calibre or copy the verified file after removing the old device version. This creates a clear checkpoint between metadata editing and device import.

5.4 Review antivirus interference only when evidence points there

Security software can interfere with temporary-file replacement or quarantine an executable, but it should not be the first assumption. Check its event history if the command reports access errors, files disappear, or changes work in one folder but consistently fail in another. Add an exception only when you have identified a specific false positive involving the official calibre installation or your controlled test folder.

A firewall is generally irrelevant to a local ebook-meta write. Investigate firewall and network settings only when the Content server, a remote library operation, or an online metadata source is the failing component.

5.5 Consider source-file damage

A malformed EPUB or damaged archive may be readable enough to open while failing during metadata replacement. Test another known-good EPUB with the same command. If the second file works, make a backup of the problem book and use calibre's Edit book tool to check it for structural errors. Do not treat successful opening in a viewer as proof that the container is healthy.

6. Use Focused Logs and a Clean Temporary Environment

Logs are most useful after the direct write-and-readback test identifies which layer is failing. Collect evidence from that layer instead of enabling every available debug option.

6.1 Capture the exact command and output

Copy the full command, its terminal output, the file path, the file's modification time, and the result of reading the same file back. Remove private paths or identifiers before sharing the information publicly. This compact record often reveals a second copy, an unsupported format, or a quoting error immediately.

6.2 Run the GUI in debug mode

If the file metadata is correct but calibre's behavior is inconsistent, close calibre and launch the GUI from a terminal with:

calibre-debug -g

Reproduce one action, such as adding the corrected format, reading metadata from the format, or sending it to a device. Then inspect the terminal output for a specific error. Avoid performing unrelated library maintenance during the same session because it makes the log harder to interpret.

6.3 Debug device detection only for device communication problems

If calibre does not detect the device or cannot communicate with it, use Preferences, Miscellaneous, Debug device detection while the device is attached. The command-line equivalent is available through calibre-debug. This diagnostic does not fix embedded metadata, so skip it when the device is detected and receives books normally.

6.4 Temporarily rule out plugins

A plugin is relevant only if it participates in metadata import, conversion, device transfer, save-to-disk processing, or file handling. Disable one suspected plugin, restart calibre, and repeat the same controlled test. If nothing changes, re-enable it before testing another possibility.

Success means the behavior changes reliably when one plugin is disabled and returns when it is re-enabled. That repeatability is stronger evidence than disabling every plugin at once.

6.5 Use a temporary clean library

Create a new empty library through Switch/create library, add only the verified test file, and inspect the imported metadata. Then change the library record through the GUI and send or export the test book if needed.

If the workflow succeeds in the temporary library, the calibre installation and basic file are working. The problem is more likely tied to the original record, library settings, plugboard, plugin, or stored format. Switch back to the original library after the test and change only the identified component.

7. Run a Clean Temporary Test Before Reinstalling

Reinstalling calibre rarely resolves a mismatch between embedded file metadata, database metadata, and device metadata. A clean test provides more useful information and avoids unnecessary disruption.

1. Copy one supported, non-protected EPUB to a writable local folder.
2. Run ebook-meta with a unique temporary title.
3. Read the same file back with ebook-meta.
4. Create a temporary empty calibre library.
5. Add the edited file and confirm which title calibre imports.
6. If device behavior is involved, delete the old device copy and send the test book once.
7. Inspect the exact exported, converted, or transferred file rather than a similarly named copy.

If all seven steps work, do not reinstall. Compare the successful workflow with your original one and look for the first difference: file path, format, book record, conversion source, plugboard, plugin, device copy, or library location.

Do not delete your main library or its metadata.db file as an experiment. Back up the library before performing repair or maintenance operations. Library database restoration is for actual database damage, not for synchronizing metadata edited by ebook-meta.

8. Quick Fix Checklist

• Edit a copied file in a normal local folder.
• Quote every path or metadata value containing spaces.
• Read the exact file back with ebook-meta.
• Confirm that the format supports writing, not merely reading.
• Test a basic title field before testing covers, tags, or series.
• Use Edit metadata when the calibre library record is the intended target.
• Use calibredb set_metadata for command-line database changes.
• Replace the format in the existing book record instead of creating a duplicate.
• Inspect converted and exported output files directly.
• Check metadata plugboards before sending to a device.
• Remove the device's old copy and allow its library to refresh.
• Test in a temporary clean library before reinstalling or deleting anything.

9. Frequently Asked Questions

9.1 Why did ebook-meta change the file but not calibre?

ebook-meta changes supported metadata embedded in the specified e-book file. calibre's main library view reads its own database record. Use the GUI's Edit metadata tools or calibredb set_metadata to change the database. Alternatively, import metadata from the corrected format into the existing record.

9.2 Does restarting calibre make it reread embedded metadata?

Normally, restarting does not make calibre replace existing database metadata with values from every stored file. Explicitly tell calibre to read metadata from the relevant format, replace the format in the intended record, or edit the database metadata directly.

9.3 Why is one metadata field ignored while the title works?

Metadata capabilities vary by format and field. A file type may support writing titles and authors but not another requested value. Verify the writable formats and options shown by your installed command, then test each field separately.

9.4 Why does my e-reader still show the old title?

The reader may still contain the old file, may cache metadata in an internal database, or may ignore the embedded field. Delete the device copy, eject safely, allow the device to refresh, and resend the verified file. If direct inspection confirms the new value but the reader still ignores it, investigate the reader's metadata limitations.

9.5 Should I re-add the book to calibre?

You can, but avoid creating an unnecessary duplicate. Select the existing book record and add or replace its format. If you need calibre's displayed fields to match the file, use the option to read metadata from that format and review the imported values before saving.

9.6 When should I stop troubleshooting ebook-meta?

Stop changing ebook-meta settings as soon as reading the same file back shows the expected metadata. That proves the command completed its job. Continue only in the layer that remains wrong, such as the calibre database, conversion output, Content server library, exported copy, transfer process, or device cache.