CTk Theme Builder

CTk Theme Builder is a desktop editor for creating, previewing, and refining themes for CustomTkinter applications.

It provides a live, visual workflow for editing CustomTkinter theme colours, supported widget geometry, palettes, and theme metadata without hand-editing theme JSON files.

The application is designed to make iterative theme work practical: you can experiment with colours, compare light and dark appearance modes, reuse palette colours across a theme, and validate the result against realistic widget rendering as you work.

Features

• Live visual editing of CustomTkinter theme colours with immediate preview feedback
• Editing of supported widget geometry properties such as corner radius and border width
• Light and dark appearance-mode workflows, including copying and flipping values between modes
• Persistent theme palette for planning, reusing, and refining colours across a theme
• Colour harmonics generation from a keystone colour to help build coherent palettes
• Bundled icon browsing with CustomTkinter code-snippet generation for available Font Awesome icons
• Drag-and-drop, clipboard, and shade-adjustment workflows for fast colour iteration
• Palette-driven cascade updates for applying a colour across related widget properties
• Theme merge, import, and export support for reuse and distribution
• Provenance metadata for themes created and maintained in the builder
• Preview and validation support for realistic widget states, including disabled rendering
• Built-in theme and palette assets to help you get started quickly

Installation

On macOS, first check that the Python you plan to use has Tk support: python3 -m tkinter should open a small test window. If it fails to import _tkinter, follow the macOS Tk instructions before creating a virtual environment.

Recommended installation from PyPI, using a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install ctk-theme-builder

If you manage several Python versions, see the optional pyenv installation route.

On Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install ctk-theme-builder

Alternative install methods for users who already use uv:

uv pip install ctk-theme-builder
uvx --from ctk-theme-builder ctk-theme-builder

Usage

Launch the application:

ctk-theme-builder

Optional command-line arguments:

ctk-theme-builder --set-appearance Dark
ctk-theme-builder --set-theme /path/to/theme.json

To migrate themes and palettes from a legacy installation:

ctktb-migrate-assets /path/to/old/install

Requirements

• Python 3.10 to 3.13
• A desktop environment capable of running Tk-based GUI applications

Documentation

• Installation and upgrade notes: docs/installs-upgrades.md
• User guide: docs/UserGuide-3.3.md
• Release notes: release-notes-3.2.4.md

Licence

Released under the MIT Licence. See LICENSE.