{"id":4489,"library":"customtkinter","title":"CustomTkinter","description":"CustomTkinter is a Python UI library based on Tkinter, designed to create modern-looking and fully customizable graphical user interfaces. It provides a consistent and aesthetically pleasing experience across Windows, macOS, and Linux platforms, enhancing standard Tkinter widgets with advanced styling. The library is actively developed, with its current version being 5.2.2.","status":"active","version":"5.2.2","language":"en","source_language":"en","source_url":"https://github.com/TomSchimansky/CustomTkinter","tags":["GUI","Tkinter","desktop-app","UI","modern-ui"],"install":[{"cmd":"pip install customtkinter","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Internal type hinting support.","package":"typing-extensions","optional":false},{"reason":"Used for version parsing and compatibility checks.","package":"packaging","optional":false},{"reason":"Enables detection of system appearance mode (light/dark).","package":"darkdetect","optional":false},{"reason":"Required for displaying images within CustomTkinter widgets, such as on CTkButton or CTkLabel.","package":"Pillow","optional":true},{"reason":"CustomTkinter is built on top of Tkinter, which in turn relies on the Tcl/Tk GUI toolkit. This is typically bundled with Python but might need system-level installation on some Linux distributions or specific environments.","package":"tk","optional":false}],"imports":[{"note":"Module name is lowercase: `customtkinter`. Classes are typically accessed as `customtkinter.CTk`, `customtkinter.CTkButton`, etc. or after aliasing: `import customtkinter as ctk`.","wrong":"from CustomTkinter import CTk","symbol":"customtkinter","correct":"import customtkinter"},{"note":"While `from customtkinter import *` works, it's generally discouraged in production code. Explicitly importing `customtkinter` and using the prefix `customtkinter.CTk` or an alias `ctk.CTk` is preferred for clarity and avoiding name clashes.","wrong":"from customtkinter import *\napp = CTk()","symbol":"CTk","correct":"import customtkinter as ctk\napp = ctk.CTk()"}],"quickstart":{"code":"import customtkinter\n\ncustomtkinter.set_appearance_mode(\"System\")  # Modes: \"System\" (default), \"Dark\", \"Light\"\ncustomtkinter.set_default_color_theme(\"blue\")  # Themes: \"blue\" (default), \"dark-blue\", \"green\"\n\napp = customtkinter.CTk() # create CTk window\napp.geometry(\"400x240\")\napp.title(\"My CTk App\")\n\ndef button_function():\n    print(\"Button pressed!\")\n\n# Create a button\nbutton = customtkinter.CTkButton(master=app, text=\"Click Me\", command=button_function)\nbutton.place(relx=0.5, rely=0.5, anchor=customtkinter.CENTER)\n\napp.mainloop()","lang":"python","description":"This quickstart initializes a basic CustomTkinter window, sets the appearance mode and color theme, and adds a centered button that prints a message when clicked."},"warnings":[{"fix":"Review the official migration guide for v5.0.0. Update font attribute names from `text_font` to `font`. Change `fg_color=None` to `fg_color='transparent'` for transparent elements. Custom theme files will need to be re-structured to the new JSON format.","message":"Version 5.0.0 introduced significant breaking changes, including: `text_font` attributes renamed to `font`, transparent color values changing from `None` to the string `'transparent'`, and a complete overhaul of custom theme file formats.","severity":"breaking","affected_versions":"5.0.0+"},{"fix":"Ensure your IDE is configured to use the correct Python interpreter associated with your virtual environment where CustomTkinter is installed. Always use `import customtkinter` (lowercase 'c') and refer to classes with the `customtkinter.` prefix (e.g., `customtkinter.CTk`).","message":"ModuleNotFoundError for 'customtkinter' often occurs due to incorrect Python interpreter selection in IDEs (like VS Code) when using virtual environments, or due to incorrect capitalization in import statements (e.g., `from CustomTkinter import CTk`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install Pillow using `pip install Pillow` if you plan to use images in your CustomTkinter application.","message":"Displaying images within CustomTkinter widgets (e.g., `CTkButton` or `CTkLabel`) requires the Pillow library to be installed separately, as it is an optional dependency.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If encountering issues related to the underlying GUI framework, ensure Tcl/Tk development packages are installed on your operating system (e.g., `sudo apt-get install python3-tk` on Debian/Ubuntu, or `brew install tcl-tk` on macOS for Homebrew Python).","message":"CustomTkinter, being built on Tkinter, implicitly relies on the Tcl/Tk GUI toolkit. While typically bundled with Python, some environments (especially minimal Linux installations or specific Python builds) may require manual installation of Tcl/Tk system packages.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}