CTkKanban

Installation

Install CTkKanban from PyPI. CustomTkinter is installed automatically as a required dependency.

python -m pip install --upgrade CTkKanBan

CTkKanban requires Python 3.10 or newer. Its package metadata accepts CustomTkinter 5.2.2 or newer below major version 7.

Although the distribution name uses capitals, import the package with its canonical lowercase module name:

import customtkinter as ctk
from ctk_kanban import CTkKanbanBoard

Public helpers can be imported from the same package root:

from ctk_kanban import (
    ActionConfig,
    BoardConfig,
    BoardModel,
    BoardModelError,
    BoardSnapshot,
    Card,
    CardRecord,
    Column,
    ColumnRecord,
    DEFAULT_FIELDS,
    DEFAULT_THEME,
    FieldDefinition,
    FieldType,
    LayoutConfig,
    TextConfig,
    merge_config,
    merge_theme,
    normalize_row,
    normalize_rows,
    rows_from_cursor,
    snapshot_from_cursors,
    snapshot_from_rows,
    __version__,
)

Release 2.1.0 Highlights

Version 2.1 keeps the focused 2.x board API while adding the flexibility needed by real applications.

Quick Start

Create a window, define columns and cards, then pack the board like any other CustomTkinter widget.

import customtkinter as ctk

from ctk_kanban import CTkKanbanBoard

ctk.set_appearance_mode("System")

app = ctk.CTk()
app.title("Project board")
app.geometry("1100x680")

board = CTkKanbanBoard(
    app,
    columns=[
        {"id": "todo", "title": "To do"},
        {"id": "doing", "title": "Doing"},
        {"id": "done", "title": "Done"},
    ],
    cards=[
        {
            "id": 1,
            "column": "todo",
            "title": "Publish CTkKanban",
            "description": "Finish the documentation and release checks.",
            "priority": "High",
            "tags": ["release", "docs"],
        }
    ],
    on_change=lambda event: print(event["type"], event["data"]),
)
board.pack(fill="both", expand=True)

app.mainloop()

Tutorial 1: Static Board

Start from static Python data without any storage dependency. Disable dragging and omit persistence callbacks when changes only need to live for the lifetime of the window.

from ctk_kanban import Card, Column, CTkKanbanBoard

columns = [
    Column(id="planned", title="Planned"),
    Column(id="shipped", title="Shipped"),
]

cards = [
    Card(
        id="docs",
        column="planned",
        title="Write documentation",
        priority="Medium",
        tags=("documentation",),
    )
]

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    enable_drag=False,
    confirm_delete=True,
)

Column and Card instances use the same validation as dictionaries. You can freely mix typed instances and mapping records in an input iterable.

Tutorial 2: Board Interaction

CTkKanban makes destructive and mutating actions visible and deliberate. Use config["actions"] or allow_card_deletion=False to remove operations that a particular application must not expose:

• Click a card body or its Edit action to select it and open the editor drawer.
• Save with Save changes, Enter outside a multiline textbox, or Ctrl+Enter anywhere in the editor.
• Press Escape or choose Cancel to close the drawer without saving.
• Drag from the handle in the card's upper-right corner. A six-pixel threshold prevents accidental drags.
• Use card menus to move up, move down, move between columns, edit, or delete.
• Use column menus to rename, move left, move right, or delete a column.

Programmatic actions use the same model and event path as the built-in UI:

board.add_card(
    {
        "id": 42,
        "column": "todo",
        "title": "Review pull request",
        "priority": "High",
        "tags": ["code-review"],
    },
    index=0,
)

board.update_card(42, {"description": "Check tests and typing."})
board.move_card(42, "doing", index=0)
board.delete_card(42)

Tutorial 3: Save Changes

The on_change callback runs once after each successful mutation. Every event contains type, before, and the latest complete snapshot in data, plus the affected record.

import json
from pathlib import Path

BOARD_FILE = Path("board.json")


def save_change(event):
    # Suitable for small local files. Avoid slow network or SQL work here.
    BOARD_FILE.write_text(
        json.dumps(event["data"], indent=2),
        encoding="utf-8",
    )


board = CTkKanbanBoard(
    app,
    columns=initial_data["columns"],
    cards=initial_data["cards"],
    on_change=save_change,
)

Tutorial 4: Complete PostgreSQL App

This example uses Psycopg 3 mapping rows, SQL aliases that match CTkKanban's schema, and load_async() so database work does not freeze the desktop window.

Install Psycopg separately; CTkKanban intentionally does not require a database driver:

python -m pip install "psycopg[binary]"

Example schema

CREATE TABLE kanban_columns (
    id          text PRIMARY KEY,
    title       text NOT NULL,
    position    integer NOT NULL
);

CREATE TABLE kanban_cards (
    id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    column_id   text NOT NULL REFERENCES kanban_columns(id),
    title       text NOT NULL,
    description text NOT NULL DEFAULT '',
    priority    text NOT NULL DEFAULT '',
    tags        text[] NOT NULL DEFAULT '{}',
    position    integer NOT NULL,
    CHECK (priority IN ('', 'Low', 'Medium', 'High', 'Critical'))
);

Fetch and display

import os

import customtkinter as ctk
import psycopg
from psycopg.rows import dict_row

from ctk_kanban import CTkKanbanBoard, snapshot_from_rows

DATABASE_URL = os.environ["DATABASE_URL"]

COLUMN_QUERY = """
    SELECT id, title
    FROM kanban_columns
    ORDER BY position
"""

CARD_QUERY = """
    SELECT
        id,
        column_id AS column,
        title,
        description,
        priority,
        tags
    FROM kanban_cards
    ORDER BY column_id, position
"""


def fetch_board():
    with psycopg.connect(DATABASE_URL, row_factory=dict_row) as connection:
        columns = connection.execute(COLUMN_QUERY).fetchall()
        cards = connection.execute(CARD_QUERY).fetchall()
    return snapshot_from_rows(columns, cards)


app = ctk.CTk()
app.geometry("1200x720")

status = ctk.CTkLabel(app, text="Connecting…")
status.pack(fill="x", padx=16, pady=(12, 0))

board = CTkKanbanBoard(app)
board.pack(fill="both", expand=True)

board.load_async(
    fetch_board,
    on_success=lambda data: status.configure(
        text=f"Loaded {len(data['cards'])} cards"
    ),
    on_error=lambda error: status.configure(text=f"Load failed: {error}"),
)

app.mainloop()

For plain tuple cursors, use rows_from_cursor() after each query. For writes, use stable IDs and positions, handle transactions in your repository layer, and feed the resulting canonical snapshot back through set_data() if the server changes any values.

Board Data Schema

A board snapshot is a mapping with exactly two keys:

{
    "columns": [
        {"id": "todo", "title": "To do"},
        {"id": "done", "title": "Done"},
    ],
    "cards": [
        {
            "id": 1,
            "column": "todo",
            "title": "Write release notes",
            "description": "Summarize version 2.",
            "priority": "Medium",
            "tags": ["release"],
        }
    ],
}

Unknown top-level snapshot keys and unknown column keys are rejected. Card mappings are intentionally extensible: schema-defined keys are normalized and other top-level card keys are deep-copied for round-tripping. Loading is atomic, so any invalid column, card, or relationship leaves the current model unchanged.

Column Records

Column list order is the board's manual left-to-right order.

Card Records

The fields above are the default schema. A custom schema may add any number of top-level values, while undeclared integration values are preserved without being edited, displayed, validated, formatted, or searched. Cards are serialized in column order and then in their manual top-to-bottom order. IDs should be stable database keys; use strings or integers when snapshots will be JSON encoded.

Card Field Schema

Pass fields to the board, model, or snapshot adapters to describe any number of card data points. One ordered definition controls normalization, generated editor controls, drawer grouping, local search, compact-card placement, custom validation, and display formatting.

fields = [
    {
        "key": "title",
        "label": "Title",
        "type": "text",
        "required": True,
        "searchable": True,
        "show_on_card": True,
        "card_role": "title",
    },
    {
        "key": "estimate",
        "label": "Estimate",
        "type": "integer",
        "min": 0,
        "max": 100,
        "section": "Planning",
        "show_on_card": True,
        "card_role": "metadata",
        "formatter": lambda value, _card: (
            "" if value is None else f"{value} pts"
        ),
    },
    {
        "key": "stage",
        "label": "Stage",
        "type": "select",
        "options": ["Discovery", "Delivery", "Review"],
        "show_on_card": True,
        "card_role": "badge",
        "colors": {"Delivery": ("#DCFCE7", "#14532D")},
    },
]

board = CTkKanbanBoard(
    app, columns=columns, cards=cards, fields=fields
)

Supported types

Definition options

Each mapping requires a unique, nonblank key and label. Unknown options are rejected.

min cannot exceed max; length bounds are nonnegative and ordered. Validators run in field order during construction, loading, updates, editor save, and schema replacement, so keep them fast and side-effect free. A required read-only field should define a default so new cards can be created.

Compact-card roles

Only show_on_card=True fields render, and empty values are omitted. A field colors match takes precedence; the built-in priority field otherwise uses priority theme tokens. formatter affects display text only.

Structural rules and runtime replacement

• id, column, and column_id are reserved and cannot be field keys.
• If title is omitted, the default title definition is inserted first.
• Title must be text or textarea and is forced to required, visible-on-card, and the sole title role.
• Fields omitted from a loaded card are only materialized when they have an explicit default or are required; a new editor presents type defaults.
• Undeclared card keys are preserved as private application metadata.

get_fields() returns detached normalized definitions. set_fields(fields) validates every existing card before committing, rebuilds cards and an open drawer, and leaves the old schema/data untouched on failure. It emits one fields_changed event only when normalization actually changes stored card data. Treat changes that add defaults, coerce types, or narrow choices as data migrations.

Snapshots

get_data() returns detached dictionaries and lists. Mutating the returned value cannot accidentally mutate the live board.

snapshot = board.get_data()
snapshot["cards"].append({...})  # Does not change the widget.

board.set_data(snapshot)         # Validates, replaces, and redraws.

set_data() does not emit on_change. This prevents a database refresh from being mistaken for a user edit and written straight back to storage.

Copy, replacement, and ordering guarantees

• get_data(), model snapshot(), record getters, schema getters, and mutation return values are detached copies.
• set_data() validates the complete candidate first. Use {"columns": [], "cards": []} to clear the board.
• Column order is left-to-right. Card order is top-to-bottom inside each column; global card output is grouped by current column order.
• Insertion indices are zero-based and may range from zero through the destination size, inclusive. None appends.
• update_card() merges values rather than replacing the record. Changing its column appends; move_card() supports an exact position.
• String and integer IDs are not coerced: 1 and "1" are distinct. A card reference must have the same type as its column ID.
• Input column_id is normalized to column in every output. Conflicting aliases are rejected.

Database Row Sources

CTkKanban includes small conversion helpers without taking a dependency on PostgreSQL, SQLite, SQLAlchemy, or any other database library.

One reusable DB-API cursor

from ctk_kanban import rows_from_cursor, snapshot_from_rows

cursor.execute("""
    SELECT id, title
    FROM kanban_columns
    ORDER BY position
""")
columns = rows_from_cursor(cursor)

cursor.execute("""
    SELECT id, column_id AS column, title,
           description, priority, tags
    FROM kanban_cards
    ORDER BY column_id, position
""")
cards = rows_from_cursor(cursor)

board.set_data(snapshot_from_rows(columns, cards, fields=fields))

Two executed cursors

from ctk_kanban import snapshot_from_cursors

snapshot = snapshot_from_cursors(columns_cursor, cards_cursor)
board.set_data(snapshot)

Feature: Editor Drawer

The built-in editor is an inspector-style drawer attached to the right side of the board. It keeps the board visible, reserves layout space at high display scaling, and only changes data after an explicit save. Its controls are generated from the active field schema.

fields = [
    {"key": "title", "label": "Title", "type": "text",
     "required": True, "card_role": "title", "show_on_card": True},
    {"key": "client", "label": "Client", "type": "text",
     "searchable": True, "card_role": "metadata", "show_on_card": True},
    {"key": "estimate", "label": "Estimate", "type": "integer", "min": 0},
    {"key": "blocked", "label": "Blocked", "type": "checkbox"},
    {"key": "due_date", "label": "Due date", "type": "date"},
]

board = CTkKanbanBoard(app, columns=columns, cards=cards, fields=fields)

Keyboard controls

Open the drawer directly when a surrounding application has its own buttons or shortcuts:

board.open_add_card_editor("todo")
board.open_edit_card_editor(card_id=17)
board.open_add_column_dialog()

Feature: Search

The toolbar search performs a case-insensitive substring match across every field marked searchable=True. The default schema searches title, description, priority, and every tag. Search filters only the rendered view; the underlying data and column counts stay intact.

board.search("critical")
board.search("database")
board.search("")  # Clear the filter.

• Search does not emit a change event.
• The toolbar summary shows visible results and total cards.
• Empty columns display No matching cards.
• Drag and positional movement are disabled until search is cleared.

Feature: Selection

Clicking a card selects it and applies the configured selected border color. Selection is board-local and exposes a detached card record:

selected = board.get_selected_card()
if selected is not None:
    print(selected["id"], selected["title"])

Deleting the selected card, or replacing the snapshot without that card, clears selection automatically. Selection itself is presentation state and does not emit on_change.

Feature: Dragging & Menus

Cards can be reordered within a column or moved between columns. The handle-only drag design preserves normal clicking and text interaction across the rest of the card.

Set enable_drag=False to remove card drag behavior while retaining movement through menus and the public API.

Feature: Change Events

Pass one on_change callback to observe every successful board mutation. Callback exceptions are logged under ctk_kanban and do not undo the in-memory change.

def board_changed(event):
    print("Operation:", event["type"])
    print("Before:", event["before"])
    print("Current:", event["data"])

    if "card" in event:
        print("Affected card:", event["card"])
    if "column" in event:
        print("Affected column:", event["column"])


board = CTkKanbanBoard(app, on_change=board_changed)

All events also contain detached before and data snapshots. A column cascade exposes removed cards through before. No event is sent for a no-op update/move, a schema replacement that leaves stored values identical, selection, search, rendering, loading presentation, or set_data().

Feature: External Card Editor

Pass on_card_open when the host application owns card editing. The callback receives a detached card dictionary and replaces the built-in editor for existing cards.

def open_application_editor(card):
    details_panel.show(card)


board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    on_card_open=open_application_editor,
)

# When your editor saves:
board.update_card(card["id"], validated_updates)

The callback is for opening an existing card. open_add_card_editor() continues to use CTkKanban's built-in add drawer.

Feature: Loading State & Async Loading

set_loading(True) updates the toolbar summary and disables toolbar inputs without changing board data. load_async() combines that state with safe background fetching and Tk-thread delivery.

thread = board.load_async(
    fetch_board,
    on_success=lambda snapshot: print(
        f"Loaded {len(snapshot['cards'])} cards"
    ),
    on_error=lambda error: print("Could not load:", error),
    clear_on_error=False,
)

print(board.is_loading)  # True while the request is pending.
print(board.load_error)  # None, or the most recent async exception.

• fetch_board runs on a daemon worker thread and must return a board snapshot mapping.
• The full snapshot is validated on the worker before it reaches the widget.
• set_data(), on_success, and on_error run on Tk's thread.
• Existing data stays visible after failure unless clear_on_error=True.
• Starting a newer load invalidates an older pending result so stale data cannot overwrite the newer request.
• A new request clears load_error. A failed request stores the original exception before on_error.
• Success applies data through set_data(), so loading does not emit on_change.
• Invalidating an old result does not forcibly stop its Python worker; it only prevents delivery.
• The returned threading.Thread can be inspected or joined by non-UI test code, but do not join it from Tk's UI thread.

Manual set_loading(True) only changes toolbar presentation. It does not create a worker, prevent API mutations, or alter data. Destroying the board invalidates pending delivery; attempting a new load after destruction raises RuntimeError.

Feature: Configuration & Permissions

config accepts a BoardConfig or a nested mapping. It keeps action availability, layout, user-facing labels, and confirmation policy separate from visual theme tokens.

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    config={
        "actions": {
            "delete_cards": False,
            "delete_columns": False,
            "move_columns": False,
        },
        "layout": {
            "show_toolbar": True,
            "column_width": 340,
            "column_height": 560,
            "editor_width": 480,
        },
        "text": {
            "board_title": "Release planning",
            "add_card": "+ New work item",
        },
        "confirm_delete": True,
    },
)

Nested mappings may be partial. Dataclass defaults fill omitted values, while unknown names are rejected. The equivalent typed form uses frozen ActionConfig, LayoutConfig, TextConfig, and BoardConfig instances. merge_config() validates either representation.

Action permissions

Every action defaults to enabled.

A disabled public mutation raises BoardModelError; a disabled UI-opening helper simply returns. Disabling card deletion also blocks delete_column(..., delete_cards=True) when cards are present, so a cascade cannot bypass the policy.

Layout and confirmation

Customizable text

All text settings must be strings. Short mechanical labels inside menus and the editor are not currently configurable.

Override precedence

Direct constructor values override structured config only when explicitly supplied: show_toolbar, enable_drag, all three dimensions, confirm_delete, and board_title. allow_card_deletion and allow_column_deletion override the corresponding action settings. Remaining keyword arguments are forwarded to the outer CTkFrame.

Feature: Styling & Themes

CTkKanban derives its default surfaces, text, inputs, buttons, hover states, and scrollbars from the active CustomTkinter theme. Set appearance and color theme before creating the board:

import customtkinter as ctk

ctk.set_appearance_mode("dark")
ctk.set_default_color_theme("green")

board = CTkKanbanBoard(app, columns=columns, cards=cards)

Override only the tokens you need. A string fixes one color in both modes; a (light, dark) pair follows appearance mode.

purple_theme = {
    "accent_color": ("#7C3AED", "#A78BFA"),
    "selected_border_color": ("#7C3AED", "#A78BFA"),
    "drop_indicator_color": ("#7C3AED", "#A78BFA"),
    "column_accent_colors": (
        ("#2563EB", "#60A5FA"),
        ("#7C3AED", "#A78BFA"),
        ("#C11574", "#F472B6"),
    ),
    "card_border_color": ("#CBD5E1", "#334155"),
}

board = CTkKanbanBoard(
    app,
    columns=columns,
    cards=cards,
    theme=purple_theme,
    corner_radius=14,  # Normal CTkFrame option for the board itself.
)

Theme tokens

Complete 97-token index

DEFAULT_THEME exposes the exact current defaults. This index lists every accepted name so a misspelling never has to be discovered by trial and error.

Color tokens accept CustomTkinter color strings or light/dark pairs. Font tokens are mappings passed to ctk.CTkFont(**mapping). Padding tokens may be scalars or the tuples used by the defaults. column_accent_colors and tag_pill_colors must be non-empty sequences because rendering cycles through them.

API: CTkKanbanBoard Constructor

CTkKanbanBoard(
    master,
    columns=(),
    cards=(),
    *,
    on_change=None,
    on_card_open=None,
    theme=None,
    fields=None,
    config=None,
    show_toolbar=None,
    enable_drag=None,
    column_width=None,
    column_height=None,
    editor_width=None,
    confirm_delete=None,
    allow_card_deletion=None,
    allow_column_deletion=None,
    board_title=None,
    **kwargs,
)

API: Board Methods

Data and rendering

Card mutations

Column mutations

Editors and loading

Board mutation methods enforce ActionConfig and raise BoardModelError when disabled. They never show confirmation dialogs; confirm_delete applies only to built-in menu requests. No-op updates and moves return the normalized record without emitting an event.

API: BoardModel

BoardModel contains the same strict data and ordering behavior without importing or creating a Tk window. It is useful in repositories, tests, command-line tools, and service layers.

from ctk_kanban import BoardModel

model = BoardModel(columns=columns, cards=cards, fields=fields)
model.add_column({"id": "blocked", "title": "Blocked"})
model.move_card(card_id=1, column_id="blocked", index=0)

validated_snapshot = model.snapshot()

update_card(card_id, updates=None, **changes) and update_column(column_id, updates=None, **changes) accept keyword changes in addition to a mapping; later keyword values win. Model update_column() also accepts a title string. load(data) requires exactly columns and cards, while load(columns=..., cards=...) is the explicit alternative; the two forms cannot be mixed.

The model returns detached records/snapshots, replaces data and schemas atomically, has no BoardConfig permissions, and emits no widget events. Invalid records, unknown IDs, duplicate IDs, out-of-range indices, protected nonempty column deletion, and unsupported updates raise BoardModelError, a subclass of ValueError.

API: Records & Types

Definition helpers

from_definition() exposes model normalization without building an entire board:

column = Column.from_definition(
    {"id": "todo", "title": "  To do  "}
)

card = Card.from_definition(
    {
        "id": 7,
        "column_id": "todo",
        "title": "  Normalize me  ",
        "tags": [" docs ", "release"],
    }
)

assert column.title == "To do"
assert card.column == "todo"
assert card.tags == ("docs", "release")

Card is intentionally a compatibility dataclass for the four default fields and cannot retain arbitrary schema keys. Use mapping records through BoardModel(fields=...) when custom values must survive normalization.

API: Data Adapters

Adapters do not execute SQL, commit, close cursors, or own connections. Pass the same field schema as the board, and convert driver-specific JSON/array values in the repository layer when they are not already the expected Python values.

API: Theme Helpers

from ctk_kanban import DEFAULT_THEME, merge_theme

print(sorted(DEFAULT_THEME))

theme = merge_theme({
    "accent_color": ("#2563EB", "#60A5FA"),
    "danger_color": ("#B42318", "#F97066"),
})

merge_theme() deep-copies overrides where possible and rejects names outside DEFAULT_THEME. It does not type-check every visual value; malformed colors, font mappings, sizes, or empty palettes may be reported when CustomTkinter constructs the affected widget.

API: Errors & Lifecycle

All widget construction, normal methods, and UI callbacks belong on Tk's main thread. Only load_async()'s no-argument fetch callable runs on a daemon worker; it must not touch Tk. Applying its snapshot and invoking its callbacks happens via the board's Tk event loop.

destroy() is idempotent. It increments the async generation so stale workers cannot deliver, cancels polling/editor animation callbacks, releases active menu and drag state, destroys managed scroll frames, and then tears down the outer widget. Starting load_async() after destruction raises RuntimeError.

Migrating from 1.x

Version 2 is intentionally incompatible with the broad 1.x framework. Treat the migration as a move to a focused widget with application-owned integration.

# Convert an application record before loading it.
card = {
    "id": row["task_id"],
    "column": row["status_id"],
    "title": row["summary"],
    "description": row.get("notes", ""),
    "priority": row.get("priority", ""),
    "tags": row.get("labels", []),
}

FAQ & Troubleshooting