All platforms · 8 min · Qwen Code checked August 18, 2026

Qwen Code custom themes: install, verify, remove, restore

Add a custom Qwen Code theme through a home-directory file or the settings map, confirm every required key and the custom type, verify it in the theme picker, then remove it and restore a built-in theme.

Edited and reviewed by CodexTheme Tools editorial. Reviewed . First published . Status: Published. User task: Install, activate, verify, remove, and restore a custom Qwen Code theme through settings.

Sources: Official Qwen Code theme documentation (required key list, custom type value, optional diff and gradient keys, theme file inside the home directory, ui.customThemes map, theme selection): https://github.com/QwenLM/qwen-code/blob/main/docs/users/configuration/themes.md, read at docs commit prefix 259951c53e61. Published Qwen Code documentation site mirror of the same theme configuration page: https://qwenlm.github.io/qwen-code-docs/en/users/configuration/themes/. Official Qwen Code repository: https://github.com/QwenLM/qwen-code. No site-owned device verification of Qwen Code or Qwen Code Desktop is claimed, and this guide is not affiliated with Qwen or Alibaba.

Platform behavior can change. Compare this guide with the Qwen Code repository at commit 259951c53e61.

Quick answer

Save the theme JSON under your home directory and point the theme setting at that path, or paste the same object into the custom themes map in your settings file and pick it in the theme picker. Include every required key with the type set to custom. Clearing the setting and deleting the file restores a built-in theme.

01Check the required key list
02Save the theme inside your home directory
03Point settings at it or paste it into the map
04Verify, then rehearse removal

Two documented ways to activate one object

A Qwen Code custom theme is a JSON object. You can save it as a file and point the theme setting at that path, or paste the same object into the custom themes map inside your settings file and pick it in the theme picker. The map is convenient for one or two themes and keeps everything in a single file; a separate file is easier to review, diff, and share. Both are edits you make in files you already own, and neither runs a command on your behalf.

Theme files only load from inside your home directory

The loader deliberately restricts theme files to paths under your home directory. A theme sitting in a temporary download folder, a shared drive, or a repository outside your home will not load, and that is a boundary rather than a bug: it keeps the client from reading colour definitions from arbitrary locations. Copy the file into a themes folder under your home directory first, then reference that path.

A missing required key is the usual failure

The documented contract requires a name, a type, a background and foreground, a light blue, five accent colours, a comment colour, and a grey. If one is missing the theme is rejected or falls back, which reads as "my theme does nothing" rather than as a validation error. The type value for a user-authored theme is custom. Optional diff and gradient entries are allowed, but everything else is unnecessary: do not add provenance or comment fields to a file whose loader expects a fixed shape.

One appearance per theme object

A theme object describes a single appearance, so a light palette and a dark palette are two objects with two distinct names. Generate them separately and label them clearly, for example one name ending in light and one in dark, instead of trying to store both in one entry. That is different from contracts that require paired values in a single file, and mixing the two mental models produces a file neither loader accepts.

Verify beyond the first screen

Confirm the theme appears in the picker, then read the interface with the JSON open beside it: background, foreground, comment colour, the accent colours on their surfaces, and diff colouring if you enabled the optional keys. Check the smallest text in the interface, not only headings and prompts. A palette that measures well on a large label can still fail on dim metadata, which is where a low-contrast accent is usually noticed.

Remove the theme and restore a built-in one

Delete the theme setting value, or delete the entry from the custom themes map, and select a built-in theme again. Then delete the file you copied if you used the file path route. Nothing else persists: no installer ran, no service was registered, and no application file was modified, so an empty setting is a complete restore.

Do not paste an object with missing required keys and assume the client will fill in the gaps, and do not keep a theme file outside your home directory. Neither produces an error you will notice; both produce a theme that silently does not apply.

Completion checklist

Frequently asked questions

Where does Qwen Code load a custom theme from?

From a JSON file inside your home directory that the theme setting points at, or from the custom themes map inside your settings file. Files outside your home directory are not loaded.

Which keys are mandatory in a Qwen Code theme?

A name, a type, a background and foreground, a light blue, the blue, purple, cyan, green, yellow, and red accents, a comment colour, and a grey. The diff and gradient entries are optional additions on top of that list.

Why is my custom theme missing from the picker?

Most often a required key is absent, the type is not custom, the JSON does not parse, or the file sits outside your home directory. Check those before changing colours, and remember that one object describes one appearance.

How do I go back to a built-in theme?

Delete the theme setting value or the map entry you added, pick a built-in theme, then delete the file you copied. No installer or service was created, so nothing else has to be undone.

Related guides