tkcalendar

Common errors

• ModuleNotFoundError: No module named 'tkcalendar'

  cause The `tkcalendar` library is not installed in the active Python environment, or there's a typo in the import statement, or the Python file is named `tkcalendar.py`.
  fix Install the library: `pip install tkcalendar`. Verify the import statement: `from tkcalendar import Calendar, DateEntry`. Rename your script if it's named `tkcalendar.py`.

• DateEntry dropdown calendar not displaying correctly (empty, white-on-white text, or vanishes)

  cause This can be caused by theme incompatibilities (especially on macOS or specific Windows themes), `grab_set` interactions, or an underlying Python issue (e.g., Python issue 38661 related to `ttk.Combobox` styling).
  fix Update `tkcalendar` to the latest version (v1.6.0+ fixed some `grab_set` issues and Python 38661 temporary fix). Try setting a `ttk` theme like 'clam' explicitly: `style = ttk.Style(); style.theme_use('clam')`. On Windows, a temporary fix for Python issue 38661 might involve overriding `_setup_style` if using older Python/tkcalendar versions.

• DateEntry widget inside a class does not display today's date automatically.

  cause This often occurs because the `StringVar` or other internal variables used by the `DateEntry` to hold its value are local to the class's `__init__` method and get garbage-collected, severing the link to the widget.
  fix Ensure that any `StringVar` instances or the `DateEntry` widget itself are stored as instance attributes (e.g., `self.my_date_entry = DateEntry(...)`) to prevent them from being garbage-collected prematurely.

• Calendar not showing up / DateEntry._date attribute is incorrect or not returning the selected date.

  cause Accessing internal attributes like `_date` directly is not the correct or reliable way to get the selected date. This also implies general display issues for the calendar.
  fix Always use the official methods `DateEntry.get_date()` (returns `datetime.date`) or `Calendar.selection_get()` (returns `datetime.date`) to retrieve the selected date. For display issues, ensure the Tkinter mainloop is running correctly and that the widget is properly packed/gridded.

Warnings

• breaking Prior to v1.3.0, `tkcalendar` set the locale globally, which could cause conflicts in applications with multiple instances or other locale-dependent components. Since v1.3.0, `babel` is used for locale handling and it no longer sets the locale globally.
  Fix: Upgrade to tkcalendar v1.3.0 or newer. Ensure 'babel' is installed alongside 'tkcalendar'.
• deprecated The `cursor` option for `Calendar` widget within `DateEntry` was renamed to `calendar_cursor` (around v1.5.0/v1.6.0) to prevent name clashes with the standard `ttk.Entry` cursor option.
  Fix: If customizing the calendar cursor within `DateEntry`, use the `calendar_cursor` option instead of `cursor`.
• gotcha When bundling applications with PyInstaller, `tkcalendar`'s dependency on `babel.numbers` may not be detected automatically, leading to `ModuleNotFoundError` at runtime.
  Fix: Use `--hidden-import babel.numbers` with PyInstaller: `pyinstaller --hidden-import babel.numbers myscript.py` or add `hiddenimports=["babel.numbers"]` to your `.spec` file.
• gotcha In `tkcalendar` versions prior to 1.6.0, using `grab_set` could cause the `DateEntry` drop-down calendar to vanish unexpectedly upon interaction.
  Fix: Upgrade to tkcalendar v1.6.0 or newer which includes a fix for this issue. If upgrading is not possible, avoid using `grab_set` on the parent window of the DateEntry or consider temporary workarounds from community forums.
• gotcha Since v1.5.1, `Calendar.config()` and `DateEntry.config()` methods now correctly accept a dictionary for configuration, aligning with standard Tkinter widget behavior. Prior versions might have had inconsistent behavior with dictionary-based configurations.
  Fix: If configuring widgets using dictionaries, ensure you are on v1.5.1 or later. For older versions, pass keyword arguments directly.

Install

• pip install tkcalendar Install stable release

Imports

• Calendar

  from tkcalendar import Calendar

• DateEntry

  from tkcalendar import DateEntry

Quickstart

This quickstart demonstrates how to create a simple Tkinter window with a DateEntry widget. It initializes the DateEntry to the current date and includes a button to retrieve the selected date, printing it to the console. The `datetime` module is often used for date manipulation.

import tkinter as tk
from tkinter import ttk
from tkcalendar import DateEntry
import datetime

def get_selected_date():
    print(f"Selected date: {cal.get_date()}")

root = tk.Tk()
root.title("tkcalendar DateEntry Demo")

ttk.Label(root, text="Select a date:").pack(padx=10, pady=5)

# Create a DateEntry widget
cal = DateEntry(root, width=12, background='darkblue',
                foreground='white', borderwidth=2,
                year=datetime.date.today().year,
                month=datetime.date.today().month,
                day=datetime.date.today().day,
                date_pattern='dd/MM/yyyy')
cal.pack(padx=10, pady=10)

ttk.Button(root, text="Get Selected Date", command=get_selected_date).pack(pady=5)

root.mainloop()