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.
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.
Completion checklist
- Every required key is present and the type is custom
- The file lives under your home directory
- Either the theme path or the settings-map entry is set, not a guess at both
- The theme appears in the picker and matches the JSON
- Clearing the setting and deleting the file restores a built-in theme
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.