CustomTkinter 快速上手：一条命令安装，30 秒跑通第一个窗口

【免费下载链接】CustomTkinterA modern and customizable python UI-library based on Tkinter项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter

CustomTkinter 是建立在 Tkinter 之上的 Python GUI 库，能让普通 Tk 界面拥有现代观感。它的安装只有一条 pip 命令，这篇文章按"值不值得装 → 怎么装 → 怎么跑 → 怎么用 → 容易踩的坑"带你走一遍，看完就能跑通第一个窗口。

先判断它适不适合你

CustomTkinter 给 Tkinter 换了一套现代外观的控件，创建方式和你写原生 tkinter 代码一致，也能和普通 Tk 元素混着放。窗口和控件颜色跟随系统深浅色模式，高分屏 DPI 缩放在 Windows 与 macOS 上自动生效，三端观感统一。常用的 CTk 控件一次列全：CTkButton、CTkLabel、CTkEntry、CTkCheckBox、CTkSwitch、CTkSlider、CTkProgressBar、CTkComboBox、CTkTabview、CTkTextbox、CTkScrollableFrame，外加 CTkToplevel 弹出窗口。

适合：

• 已经在用 Tkinter，但受够了老派外观
• 需要跨平台一致的工具类小应用
• 想给现有 Tkinter 项目换皮，代码改动量很小
• 想要现成的深色/浅色主题，不想自己画控件

不适合：需要庞大第三方控件生态的场景，Qt 系更划算。

环境与版本要求

一条命令安装 CustomTkinter

跑命令前先确认解释器版本：python --version，低于 3.7 的先去官网升级。然后装库并立刻验证：

pip install customtkinter python -c "import customtkinter; print(customtkinter.__version__)"

第二行应打印 6.0.0。如果数字对不上，多半是pip和python指向了不同解释器，检查一下环境。系统只有pip3时，把上面命令换成pip3 install customtkinter即可。这个库迭代很快，隔段时间跑一次pip install customtkinter --upgrade保持最新。

30 秒创建第一个窗口

新建一个 py 文件，写入下面的最小示例。思路：用CTk建主窗口，用CTkButton替换 tkinter 的 Button，pack、grid、place布局照旧可用。

import customtkinter customtkinter.set_appearance_mode("System") # 跟随系统深浅色 customtkinter.set_default_color_theme("blue") # 默认蓝色主题 app = customtkinter.CTk() app.title("My First App") app.geometry("400x240") def on_click(): print("button clicked") button = customtkinter.CTkButton(master=app, text="CTkButton", command=on_click) button.place(relx=0.5, rely=0.5, anchor=customtkinter.CENTER) app.mainloop()

注意开头两行全局设置：外观模式和主题对当前进程全局生效，写一次即可；按钮的command参数就是点击回调，语义和 tkinter 的 Button 相同。如果窗口一闪而过，多半是漏了末尾的app.mainloop()——它负责启动事件循环。

跑起来是一个居中按钮的窗口，macOS 上效果如下：

想看全部控件长什么样，仓库自带的 complex_example 是最佳起点，Windows 11 深色模式下的完整界面：

上手后最常用的三个能力

1. 切换主题和外观模式

外观模式三选一："System"（默认，跟随系统）、"Light"、"Dark"。内置 4 个颜色主题：

换主题一行搞定：customtkinter.set_default_color_theme("green")。外观模式也能运行时切换，把set_appearance_mode接到 CTkOptionMenu 的command上，就能做出"设置里点一下、全界面变深色"的效果。

主题本质是 JSON 文件，内置的放在customtkinter/assets/themes/目录；set_default_color_theme传自定义 json 的路径，就能加载自己的配色。

2. 可滚动框架和带图按钮

CTkScrollableFrame支持垂直/水平两个方向滚动，里面能放任意控件，做设置页、列表页很常用：

frame = customtkinter.CTkScrollableFrame(master=app, width=350, height=250) frame.pack(pady=20) for i in range(20): customtkinter.CTkLabel(frame, text=f"项目 {i + 1}").pack(pady=5)

按钮挂图片也简单：把 PIL 加载的图像传给CTkButton的image参数，再用compound控制图文相对位置，完整写法参考 examples/image_example.py。

3. Showroom：零代码控件展厅

6.0.0 起装好库就有展厅可用：import customtkinter as ctk后调用ctk.run_showroom()，打开一个包含全部控件的窗口。侧边栏能实时切主题、外观模式和 UI 缩放（80%~120%），调参数、看效果都很省事。

常见坑与版本建议 ⚠️

• macOS 深色标题栏不生效：需要 Python 3.10+ 或 Anaconda 版 Python（Tcl/Tk ≥ 8.6.9），否则窗口头部仍是浅色。
• Linux 上界面偏小：高分屏 DPI 缩放只覆盖 Windows 和 macOS，Linux 按 100% 绘制，属正常现象。
• 界面发虚、缩放异常：优先--upgrade到最新版，6.0.0 修复了 configure/cget 与多项交互行为。
• 想跟最新开发进度：git clone https://gitcode.com/gh_mirrors/cu/CustomTkinter后在仓库目录执行pip install -e .做源码安装。
• 控件行为拿不准：test/unit_tests/ 的单元测试与 examples/ 的示例是最好的活文档。

下一步可以做什么

• 把窗口改成CTkEntry+CTkButton组合，做一个输入回显小表单
• 用CTkTabview把功能拆到选项卡里，模仿 complex_example 的布局
• 写一份自己的主题 json，用set_default_color_theme(路径)加载
• 打开 examples/complex_example.py，对照源码理解侧边栏与网格布局
• 加一个CTkToplevel弹出层，体验多窗口程序

【免费下载链接】CustomTkinterA modern and customizable python UI-library based on Tkinter项目地址: https://gitcode.com/gh_mirrors/cu/CustomTkinter