SumatraPDF Theme Colors Not Applying: How to Fix Custom Themes

When SumatraPDF theme colors are not applying, the cause is usually a formatting error in the Themes array, a mismatch between the custom theme name and the active Theme setting, or editing the wrong SumatraPDF-settings.txt file. A theme can also appear partially successful because some standard Windows controls do not accept every custom color. The steps below isolate these possibilities without deleting your working configuration or changing how documents are rendered.

1. Confirm the Symptom With a Simple Test

Before editing more settings, determine whether the problem affects the SumatraPDF interface or the document itself. Custom theme settings primarily control interface colors and supported reading surfaces. They do not rewrite a PDF page or replace the colors embedded in a PDF.

Open SumatraPDF without relying on a complicated document. If necessary, use a simple local PDF or another supported file that opens reliably. Then look at interface areas such as the toolbar, tab area, sidebar, start page, window background around a page, and supported text-based reading views.

1.1 Identify What Actually Changed

Compare the interface against the colors you entered for these settings:

• TextColor controls text in theme-aware interface areas.
• BackgroundColor controls the main theme background in supported areas.
• ControlBackgroundColor controls the background of theme-aware controls.
• LinkColor controls links where SumatraPDF applies theme link styling.
• ColorizeControls tells SumatraPDF whether to recolor supported controls.

If the toolbar or sidebar changes but a PDF page remains white, the custom theme may already be working. PDF pages contain their own colors, and changing the application theme is different from applying document inversion or a document-specific color replacement feature.

If none of the interface changes, continue with the settings-file checks. If only native-looking buttons, menus, scrollbars, or dialog elements retain their Windows appearance, skip ahead to the explanation of standard Windows controls.

1.2 Use an Obvious Temporary Color

For diagnosis, temporarily give one theme property an unmistakable color. A strong dark background or bright link color is easier to verify than two similar gray shades. Change only one property at a time, save the file, and reload SumatraPDF as described below.

Success means the intended interface area visibly adopts the test color. Once that happens, stop changing the theme structure. Replace the test color with your preferred value and leave the working syntax intact.

2. Check the Theme Definition and Selection

The most common SumatraPDF theme colors not applying fix is to correct the relationship between the Themes array and the active Theme value. Defining a theme does not necessarily select it. SumatraPDF must be able to parse the entry, and its name must be selected exactly.

2.1 Verify the Themes Array Formatting

A custom entry belongs inside the outer Themes array. Each individual theme is also enclosed in square brackets. A simplified custom entry follows this general structure:

Themes = [
    [
        Name = My Custom Theme
        TextColor = #e8e8e8
        BackgroundColor = #202124
        ControlBackgroundColor = #303134
        LinkColor = #8ab4f8
        ColorizeControls = true
    ]
]
Theme = My Custom Theme

Preserve any other theme entries already present in your file. Do not replace the complete array with the example unless you intentionally want only that entry. The important detail is the nesting: one pair of square brackets surrounds the array, and another pair surrounds each theme definition.

Common square bracket mistakes include:

• Leaving out the closing bracket for the custom theme.
• Leaving out the closing bracket for the complete Themes array.
• Placing color properties outside the individual theme entry.
• Accidentally nesting one theme inside another theme.
• Deleting a neighboring bracket while pasting a new entry.
• Using braces or parentheses where the settings format expects square brackets.

A malformed array can cause the custom entry to disappear from the theme selector or prevent later settings from being read as intended. Correct the brackets, save the file as plain text, restart or reload SumatraPDF, and inspect the theme list again.

Success means the custom name appears as a selectable theme and selecting it changes at least the supported interface colors. Once the entry appears and works, stop rearranging brackets.

2.2 Match the Theme Name Exactly

The value assigned to Theme must match the custom entry's Name. Check spelling, spaces, and capitalization rather than assuming two visually similar names are identical.

[
    Name = Evening Blue
    TextColor = #f0f3f8
    BackgroundColor = #18212b
    ControlBackgroundColor = #243342
    LinkColor = #78b7ff
    ColorizeControls = true
]

Theme = Evening Blue

If the entry says Name = Evening Blue but the active setting says Theme = EveningBlue, SumatraPDF cannot select that entry by the intended name. Duplicate names can also make troubleshooting confusing, so give every custom theme a unique, descriptive name.

After correcting the name, choose the theme from Settings > Theme if that menu is available in your build. You can also open the Command Palette and search for the theme-related command. Selecting through the interface is useful because it confirms that SumatraPDF recognized the entry instead of merely preserving text in the file.

Success means the selected theme remains active after closing and reopening SumatraPDF. If it does, settings persistence is working and no reinstall is needed.

2.3 Check Every Color Value

Use consistent hexadecimal color values in the expected form, such as #202124. During troubleshooting, avoid unusual copied characters, smart punctuation, inline annotations, or partially entered color values. If you copied a theme from a web page, retype a suspicious line manually in a plain-text editor.

If the theme stopped working immediately after one color was edited, restore that line first. Do not change all five properties simultaneously because that makes it harder to identify the invalid entry.

Success means the theme becomes available and the corrected property changes its corresponding interface area. At that point, keep the validated value and move no other lines.

3. Check Whether You Are Editing the Active Settings File

Installed and portable copies of SumatraPDF can use different settings locations. This is especially important when both copies exist on the same computer. Editing a file beside one executable will not affect a different SumatraPDF instance launched by a shortcut, file association, taskbar icon, or Windows search result.

3.1 Distinguish Installed and Portable Mode

A portable copy is commonly run directly from a folder and can keep its settings near the executable when that location is writable. An installed copy normally uses the current Windows user's application-data location. The exact active location should be confirmed from the running application rather than guessed.

Use SumatraPDF's advanced settings command to open the settings file when possible. This is safer than searching the drive for files with the same name. If the file opens from within the application, note its folder before making changes.

Then verify how SumatraPDF was launched:

1. Close every SumatraPDF window.
2. Launch the exact executable whose settings you edited.
3. Open the advanced settings file from that instance.
4. Confirm that your custom theme entry is present.
5. Select the custom theme and restart the same executable.

Success means the custom theme appears and persists when that particular executable is reopened. If launching from a PDF file produces different colors, the Windows file association may point to another installed or portable copy.

3.2 Check Shortcuts and File Associations

If the theme works when SumatraPDF is opened directly but not when a document is double-clicked, the theme itself is probably valid. Windows may be opening the document with another SumatraPDF executable or an entirely different reader.

Check the executable path used by your shortcut and compare it with the copy associated with the affected file type. PDFs, EPUB files, comic archives, CHM files, DjVu files, XPS files, and images can each have separate Windows associations.

Set the intended SumatraPDF copy as the default application only if you want that behavior. This is an association issue, not a reason to delete themes. Success means direct launches and double-clicked documents open the same application instance with the same selected theme.

3.3 Rule Out Folder Write Restrictions

A portable copy stored under a protected location may not be able to save settings beside its executable. Read-only folders, controlled corporate environments, or restrictive permissions can make a theme appear to work for one session and disappear after restart.

Move a test copy to a normal user-writable folder, such as a folder inside your user profile, and repeat the selection test. Do not weaken system-wide security settings merely to save a theme.

Success means the selected custom theme remains active after the portable copy is closed and reopened. If it persists in the writable folder, the original location or its permissions caused the problem.

4. Understand Partial Recoloring and Document Differences

A custom theme does not guarantee that every pixel in every window will use your chosen palette. SumatraPDF combines its own interface with controls and dialogs supplied or influenced by Windows. Some standard controls may retain system colors, visual styles, or accessibility behavior.

4.1 Why Some Controls Do Not Fully Recolor

ColorizeControls = true enables recoloring for controls that SumatraPDF can theme. It does not force every native Windows component, file picker, print dialog, title bar, scrollbar, or third-party dialog to accept the custom palette.

This means a partially recolored interface is not automatically a broken theme. If the main theme-aware areas use your colors while a standard dialog remains light, further changes to TextColor or ControlBackgroundColor may not affect that dialog.

Success in this case means SumatraPDF-owned, theme-aware areas change consistently and the theme remains selected after restart. Stop editing when only isolated native controls retain Windows styling.

4.2 Why the Document Page May Stay Unchanged

PDF, image, XPS, DjVu, comic, and other fixed-layout content generally carries its own visual appearance. Theme colors are not a universal document recoloring system. A white PDF page can therefore remain white while the surrounding SumatraPDF interface becomes dark.

Text-oriented formats may expose more reader-controlled presentation than fixed-layout pages, but behavior varies by format and rendering path. Test the interface independently from the document before concluding that SumatraPDF is not working.

Document permissions, codecs, Ghostscript, printer drivers, and external tools are generally unrelated when the only symptom is that a custom theme entry is missing or partially applied. Investigate those components only when the document itself fails to open, render, convert, or print. They will not normally repair a malformed Themes array.

5. Inspect or Reset SumatraPDF-settings.txt Safely

If the custom theme keeps disappearing, inspect the active SumatraPDF-settings.txt file without destroying other preferences. SumatraPDF may rewrite its settings when it closes, so editing while the application is running can overwrite your changes.

5.1 Back Up Before Editing

1. Close all SumatraPDF windows.
2. Locate the active settings file using the application when possible.
3. Copy it to a clearly named backup file.
4. Open the original in a plain-text editor.
5. Correct only the custom theme block and active Theme value.
6. Save the file, reopen SumatraPDF, and select the theme.

A backup preserves favorites, history, layout preferences, and other custom settings that may be stored in the same file. Avoid using a word processor because it may introduce formatting or save in an unsuitable document format.

5.2 Look for Duplicate or Damaged Entries

Search the file for Themes, the custom theme name, and Theme =. Confirm that you do not have multiple conflicting active settings or duplicate custom names. Also inspect the lines immediately before and after the theme array because a missing bracket elsewhere can affect how later content is interpreted.

If you cannot find the syntax problem, restore the backup before trying another method. Repeatedly editing a damaged file without a known-good copy can create additional symptoms.

5.3 Reset Only When Necessary

A complete settings reset should be a diagnostic step, not the first response. With SumatraPDF closed and the original safely backed up, rename the active settings file rather than deleting it. Start SumatraPDF so it can create a fresh configuration, then add one minimal custom theme.

If the minimal theme works, the old file likely contains a malformed section, duplicate entry, or conflicting customization. Rebuild only the settings you need instead of immediately pasting the entire old file into the new one.

Success means the fresh configuration recognizes the minimal custom theme and retains it after restart. Stop resetting at that point. Compare the old and new files carefully if you need to recover additional preferences.

6. Run a Clean Temporary Test

Before reinstalling SumatraPDF, test a separate copy in a writable temporary folder. The goal is to separate application behavior from the existing configuration, shortcuts, and file associations.

6.1 Create a Minimal Test Theme

Use a portable copy obtained from the official SumatraPDF source, place it in a user-writable folder, and run it directly. Open its active advanced settings file and add only one uniquely named theme with obvious colors.

Do not copy the full old settings file into the test folder. That would reproduce any syntax problem you are trying to isolate. Keep the test independent and launch the executable directly rather than through an existing shortcut.

If the theme works in the clean test, the program's theme support is functioning. The likely causes are the original settings file, the wrong executable, a protected portable folder, or a shortcut or association that launches another copy.

If the same minimal theme does not appear, recheck the array brackets, theme name, and whether the application actually reopened the file you edited. Reinstallation is unlikely to correct invalid custom syntax because an installer does not know how you intended the theme entry to be structured.

7. Quick Fix Checklist

• Confirm you are changing interface colors, not expecting a PDF page to be recolored.
• Open the active advanced settings file from the SumatraPDF instance you actually use.
• Close SumatraPDF before making final manual edits.
• Place every custom theme inside the outer Themes array.
• Enclose each individual theme in its own square brackets.
• Match Theme exactly to the custom theme's Name.
• Use valid values for TextColor, BackgroundColor, ControlBackgroundColor, and LinkColor.
• Set ColorizeControls = true when you want supported controls recolored.
• Select the theme through Settings > Theme or the Command Palette.
• Check whether shortcuts and file associations launch a different SumatraPDF copy.
• Test portable mode from a writable user folder.
• Expect some standard Windows controls and dialogs to retain system styling.
• Back up and rename the settings file before attempting a reset.
• Run a clean temporary test before reinstalling or deleting preferences.

Stop troubleshooting as soon as the custom theme appears in the selector, applies to supported interface areas, and remains selected after a restart. A fixed-layout document retaining its original colors, or an isolated Windows dialog retaining system colors, does not mean the theme failed.

8. Frequently Asked Questions

8.1 Why does my custom theme disappear from the theme menu?

The most likely cause is a malformed Themes array. Check the outer square brackets, the brackets around each individual theme, and the lines immediately surrounding your entry. Also confirm that you edited the settings file used by the running executable.

8.2 Why do only some SumatraPDF controls change color?

SumatraPDF can recolor theme-aware controls, especially when ColorizeControls is enabled, but some controls and dialogs use standard Windows styling. If the main interface adopts your colors and the selection persists, partial native styling is expected and does not require a settings reset.

8.3 Why does the background change but the PDF page stay white?

The application theme and the content of a PDF page are separate. A PDF normally defines its own page background, text, graphics, and images. Theme settings can change supported interface areas without changing the document itself.

8.4 Should I reinstall SumatraPDF when a custom theme is not working?

Usually not. First verify the syntax, active theme name, settings-file location, portable folder permissions, shortcut target, and file association. A clean portable test is more informative than reinstalling because it shows whether the existing configuration is responsible.

8.5 Why does the theme work when I launch SumatraPDF directly but not when I double-click a file?

Windows is probably launching a different executable for that file type. Compare the associated application with the installed or portable copy you configured. Once both launch paths point to the intended copy, the same settings and theme should appear.

8.6 How can I reset the theme without losing all my settings?

Close SumatraPDF and back up the active SumatraPDF-settings.txt file. First remove or repair only the custom theme block and active Theme line. If a full diagnostic reset is necessary, rename the file instead of deleting it so you can restore preferences later.