Calibre Plugin Customization Not Saving: How to Fix It

When calibre plugin customization is not saving, the symptom usually falls into one of four categories: the change was never committed, calibre is reading a different configuration folder, the plugin stores that option somewhere other than expected, or another process is restoring an older configuration. The safest way to diagnose the problem is to change one harmless setting, restart calibre correctly, and follow that setting from the plugin window to the configuration folder. Avoid reinstalling calibre or deleting your library until you complete the focused tests below. Plugin settings normally belong to calibre's configuration, not to the books in your library, so destructive library changes rarely solve this particular problem.

1. Confirm the Symptom With a Small Safe Test

Begin by proving exactly what is failing. This prevents a plugin behavior problem from being mistaken for a settings persistence problem.

1.1 Choose One Reversible Setting

Open Preferences > Advanced > Plugins, select the affected plugin, and choose its customization or configuration option. Depending on the plugin, the button may be labeled Customize plugin, Configure plugin, or something specific to that plugin.

Change one setting that is easy to recognize and safe to reverse. Good tests include changing a visible label, switching a noncritical checkbox, selecting a different optional action, or changing a harmless default value. Do not change several options at once because you will not know which one failed.

Write down the old and new values. Then use the plugin window's OK, Save, or Apply button. If a second Preferences window remains open, confirm that window as well. Closing a dialog with its window close button may cancel changes in some interfaces.

Success looks like this: when you immediately reopen the plugin's configuration window, the new value is still displayed. If it is already gone, the setting was not committed or the plugin rejected it. Stop testing restarts for the moment and verify that every dialog was confirmed.

1.2 Restart Calibre Completely

Some plugin settings take effect immediately, while others are read only when calibre or a plugin component starts. Close every calibre window, including the E-book viewer and editor if they are open. Also check for active calibre processes, tray utilities, command-line jobs, or a running Content server launched under the same user account.

Start calibre again and reopen the plugin configuration. Test the same setting before performing another task.

Success looks like this: the new value remains selected after restart and the related plugin behavior matches it. Stop changing settings once this happens. The problem was probably an unconfirmed dialog or a restart requirement rather than damaged configuration data.

2. Verify the Customization Workflow and Setting Scope

Not every option that affects a plugin is stored in the same place. A setting may apply globally, to one library, to one device, to one conversion job, or only to the book currently being edited. Confirming the setting's scope is essential when a saved option appears to revert.

2.1 Use the Plugin's Own Configuration Entry

Configure the plugin through the interface intended by its author. Start with Preferences > Advanced > Plugins, select the exact plugin name, and open its customization window. A plugin toolbar button or context menu may offer a separate configuration screen with different settings.

Do not assume that a similarly named calibre preference controls the plugin. For example, a metadata plugin may have its own source preferences, while calibre also has general metadata download settings. A device plugin can have driver-specific options that are available only while the device is connected. A conversion plugin may expose defaults in Preferences but allow book-specific conversion options to override them.

Success looks like this: changing the option through the correct plugin screen alters the intended behavior without changing unrelated calibre features.

2.2 Check Whether the Setting Is Global or Library Specific

Switching libraries is a useful diagnostic step. Save one test setting in the current library, switch to another library if one is available, and inspect the same option. If the value differs by library, the plugin may intentionally maintain library-specific preferences.

Some plugins also store information in custom columns, saved searches, book metadata, or a database associated with the active library. In that case, opening a different library can make the plugin appear to have forgotten its settings even though its global configuration is intact.

If the issue occurs only with one book, verify whether the plugin reads that book's metadata or stored identifiers. A metadata source option, conversion preference, or editor setting attached to an individual book can override a general default.

Success looks like this: the setting persists within its intended scope. Stop trying to force identical behavior across libraries if the plugin documentation says the option is library specific.

2.3 Look for Job-Specific and Device-Specific Overrides

If the plugin runs during conversion, book import, metadata download, news retrieval, or transfer to a device, check the options shown at the moment the job is launched. Previously saved per-book conversion settings can take precedence over defaults. Likewise, device plugins may keep separate rules for internal storage, storage cards, formats, collections, or connected device models.

For a device-related plugin, connect the device before opening the relevant configuration. Confirm that it is connected in the correct USB file-transfer mode and appears in calibre. Settings for one detected driver will not necessarily apply if the device later connects through a different protocol or is treated as a folder.

Success looks like this: a new test job or device transfer uses the changed option. Existing output files will not normally be rewritten automatically, so judge the result using a fresh operation.

3. Check the Calibre Configuration Folder

Plugin settings are commonly stored under calibre's configuration folder. If calibre cannot write there, writes to a different folder, or has its files rolled back by another program, customizations may disappear after restart.

3.1 Open the Folder From Inside Calibre

Go to Preferences > Advanced > Miscellaneous and select Open calibre configuration folder. Opening it from calibre is safer than guessing its location because environment variables, portable installations, and custom launch scripts can redirect configuration storage.

Keep this folder open. Make your single test change, save it, and look for recently modified files or plugin-related folders. You do not need to edit these files. The goal is simply to see whether calibre can update its active configuration location.

If no file timestamp changes, close calibre and test whether your operating system account can create and delete a harmless temporary text file in that folder. Do not delete or rename calibre's existing files.

Success looks like this: your account can write to the folder, calibre updates configuration data after you save the test setting, and the value survives a restart.

3.2 Correct Permission and Ownership Problems

On Windows, inspect the folder's Properties and Security settings. Make sure your normal account has permission to modify its contents. A configuration folder copied from another Windows account, restored by an administrator, or extracted from a protected archive may retain restrictive permissions.

On macOS, use Finder's Get Info panel to inspect Sharing and Permissions. Settings copied from another Mac or restored under a different account may have the wrong owner. On Linux, check that the user launching calibre owns the relevant configuration files and has write permission. This is especially important if calibre was previously run with sudo or under another user account.

Do not solve the problem by granting unrestricted access to everyone. Correct ownership and give your own account the normal permissions it needs.

Success looks like this: saving the test option updates the configuration and no permission error appears in debug output. Once the setting persists, stop changing folder permissions.

3.3 Check for a Redirected Configuration Directory

The CALIBRE_CONFIG_DIRECTORY environment variable tells calibre where to read and store configuration files. A shortcut, script, shell profile, application launcher, or managed-computer policy may set it without being obvious from the graphical interface.

Compare the folder opened from calibre with the location you expected. If two shortcuts open calibre with different environments, each launch can appear to use different plugin settings. The same confusion can occur when a graphical session and a terminal session use different environment variables.

If you use command-line tools, run calibre-debug --paths from the same environment used to launch calibre. Review the reported paths rather than modifying them immediately.

Success looks like this: every normal launch uses the same active configuration folder and shows the same plugin setting.

3.4 Account for Calibre Portable

Calibre Portable for Windows keeps its libraries and settings together inside the portable installation area. If you launch a standard installed copy one day and calibre-portable.exe another day, the two instances may use different settings.

Always start the intended portable executable. Confirm that the portable folder is writable and is not on read-only media. Avoid placing it in a protected system directory. If it is on a USB drive, check the drive for errors and eject it safely after calibre has completely closed.

Cloud-syncing the entire portable folder while calibre is running can also cause conflicts. Pause synchronization during the test, save one setting, close calibre, allow syncing to finish, and reopen the same portable copy.

Success looks like this: the test value survives a full portable restart from the same folder and remains intact after the drive is reconnected.

4. Rule Out Sync, Security, and Concurrent-Process Interference

A successful write can still be undone if another program replaces the configuration with an older copy.

4.1 Pause Cloud Sync and Backup Restoration

If the configuration folder is inside OneDrive, Dropbox, iCloud Drive, a roaming profile, a network home directory, or an automated backup-and-restore system, temporarily pause that service. Conflict resolution may restore an older configuration file shortly after calibre saves it.

Make the single test change while synchronization is paused, restart calibre, and inspect the value. If it now persists, configure the sync service to avoid live conflict restoration or move the active calibre configuration to a stable local location using a supported setup.

Success looks like this: the setting remains saved locally and continues to persist after synchronization is resumed without a conflict.

4.2 Check Antivirus and Controlled Folder Protection

Security software can permit calibre to run while blocking it from modifying particular folders. Review recent protection history for blocked actions involving calibre or its configuration files. If an entry clearly corresponds to your test, allow the official calibre application through the relevant protection feature rather than disabling all security software.

Firewall settings are usually relevant only when the plugin contacts an online service or local server. A firewall can prevent a plugin action from succeeding, but it normally does not explain a checkbox reverting inside the configuration dialog. Treat connection failure and settings persistence as separate symptoms unless debug output connects them.

Success looks like this: calibre can update its configuration, and the plugin's saved value remains after restart.

4.3 Close Duplicate Calibre Instances

Two calibre instances using the same configuration may save different copies of a setting. The instance closed last may overwrite newer values. This can happen with remote sessions, multiple desktop sessions, portable and installed copies, or a background server process running under the same profile.

Close all calibre components before testing. If necessary, sign out of other desktop sessions or restart the computer, then launch only one copy and repeat the one-setting test.

Success looks like this: one controlled instance saves and reloads the new value consistently.

5. Use Debug Output to Identify the Failing Layer

If the configuration still reverts, collect evidence before reinstalling anything. Debug output can reveal permission errors, invalid values, plugin exceptions, and configuration paths.

5.1 Restart Calibre in Debug Mode

Right-click the Preferences button and choose Restart in debug mode. You can also use the documented keyboard shortcut Ctrl+Shift+R where available, or launch the graphical interface with calibre-debug -g.

After calibre restarts, open the plugin configuration, change the same test setting, save it, reproduce the failure, and close calibre normally. Review the generated text output. Search for the plugin name and terms such as error, exception, permission, denied, config, or write.

Success looks like this: the log identifies a specific file, rejected value, missing dependency, or plugin exception. Address only that cause, then repeat the test.

5.2 Distinguish Plugin Failure From Core Calibre Behavior

Test whether an ordinary calibre preference survives restart. Choose one harmless interface preference, save it, restart, and check it. If both the calibre preference and plugin setting revert, focus on the configuration folder, permissions, environment, or sync process. If normal calibre preferences save correctly but only one plugin fails, the problem is probably plugin-specific.

Third-party plugins are separate from calibre itself. Their support information is typically provided by the plugin author, often through the plugin's official support thread. Record the plugin name, plugin version shown in calibre, operating system, exact test setting, and relevant debug error before asking for help.

Success looks like this: you can clearly state whether the failure affects all preferences or only one plugin. Stop making broad system changes once the issue is isolated to a single plugin.

6. Run a Clean Temporary Test Before Reinstalling

A clean configuration test is safer and more informative than deleting your library. Your calibre library contains books and metadata, while plugin configuration is generally stored separately.

6.1 Protect Existing Data First

Close calibre and back up the current configuration folder before testing. Do not move, rename, or delete the library folder. Do not edit metadata.db. Reinstalling calibre generally does not reset configuration, so it may leave the exact problem untouched.

Create a new empty folder in a normal local location that your account can write to. Advanced users can temporarily point CALIBRE_CONFIG_DIRECTORY to that folder and launch calibre from the same controlled environment. Install only the affected plugin, configure one harmless setting, and restart.

Success looks like this: the plugin saves correctly in the clean profile. That result indicates the original configuration, another plugin, or an external process is involved. It does not indicate a damaged library.

6.2 Test the Plugin Without Other Variables

Use a temporary empty library or a copy containing one non-sensitive test book. Install no unrelated plugins. Avoid device connections, cloud folders, network shares, Content server changes, metadata downloads, and conversion jobs until the setting itself survives restart.

If the setting still fails in a clean writable configuration, capture debug output and contact the plugin's support channel. The plugin may not save that option correctly on your platform, may reject the entered value, or may require a component-specific restart.

If it succeeds, return to the original profile and disable other recently changed plugins one at a time. Do not replace the original configuration wholesale until you understand which component causes the conflict.

7. Quick Fix Checklist

• Change only one safe, recognizable plugin option.
• Use the plugin's intended configuration or customization screen.
• Click Save, Apply, or OK in every open dialog.
• Close all calibre windows and processes before restarting.
• Confirm whether the option is global, library-specific, device-specific, or job-specific.
• Open the active configuration folder from Preferences instead of guessing its location.
• Verify that your user account can write to that folder.
• Check whether CALIBRE_CONFIG_DIRECTORY redirects the active profile.
• Launch the same installed or portable copy every time.
• Pause cloud sync and close duplicate calibre instances during testing.
• Review security software for blocked configuration writes.
• Use debug mode to find plugin exceptions and permission errors.
• Test a normal calibre preference to separate core and plugin failures.
• Use a clean temporary configuration before reinstalling or deleting anything.
• Stop changing settings as soon as the test value survives restart and works.

8. Frequently Asked Questions

8.1 Why Does a Plugin Setting Stay Until I Restart Calibre?

The plugin may be displaying the changed value in memory without successfully writing it to disk. The usual causes are an unconfirmed dialog, a configuration folder permission problem, a plugin save error, or another program restoring an older file. Test one option, save every dialog, and use debug mode if the value disappears after a complete restart.

8.2 Do All Plugin Changes Require a Restart?

No. Some settings apply immediately, while others require the main interface, worker processes, viewer, editor, device connection, or Content server to restart. When uncertain, close every calibre component and reopen it. If the setting survives but the behavior does not change, investigate the component that uses the option rather than repeatedly editing the preference.

8.3 Will Reinstalling Calibre Reset Plugin Settings?

Usually, reinstalling the application is not an effective first fix because settings and plugins are stored in calibre's configuration folder. A reinstall may leave the problematic configuration unchanged. Run a clean temporary configuration test first because it separates application files from profile-related problems without risking your library.

8.4 Are Plugin Settings Stored in the Calibre Library?

Many plugin settings are stored in calibre's configuration folder, but plugins can also maintain library-specific data, custom columns, metadata, or per-book values. If an option changes when you switch libraries, check the plugin's documented scope before assuming that saving failed.

8.5 Why Are Portable Plugin Settings Different?

Calibre Portable keeps its settings with the portable installation. Opening an installed copy of calibre can load a different profile. Always start the same calibre-portable.exe, make sure its folder is writable, and avoid live sync conflicts while calibre is running.

8.6 When Should I Contact the Plugin Author?

Contact the plugin's support channel when normal calibre preferences save correctly, the failure affects only that plugin, and the same problem occurs in a clean writable configuration. Include the plugin name, displayed version, operating system, exact setting tested, steps to reproduce the issue, and relevant debug output. Do not include passwords, email credentials, server tokens, or private library data.