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 系更划算。
环境与版本要求
| 项目 | 要求 |
|---|---|
| Python | ≥ 3.7（推荐 3.9+） |
| 库当前版本 | 6.0.0 |
| 第三方依赖 | darkdetect、packaging，pip 自动处理 |
| 平台 | Windows / macOS / Linux |
一条命令安装 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 个颜色主题：
| 主题 | 观感 |
|---|---|
blue | 默认，蓝灰色系，最百搭 |
dark-blue | 更沉的蓝，适合纯深色应用 |
green | 绿色强调色，区分度高 |
gold | 6.0.0 新增，金色强调色 |
换主题一行搞定：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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
