DEV Community

Cover image for Build a Pomodoro Timer App with Python Tkinter
Muhammad Saud
Muhammad Saud

Posted on Originally published at logicstack.org

Build a Pomodoro Timer App with Python Tkinter

The Pomodoro Technique is a focus method created by Francesco Cirillo in the 1980s. Work runs in 25 minute blocks called Pomodoros, each followed by a 5 minute break, and after four Pomodoros the break grows to 15 minutes. It matters because it turns a plan to focus into a timer that decides when to work and when to rest.

Key takeaways

  • Tkinter ships with Python, so this desktop app needs no extra install.
  • The countdown uses root.after(), which keeps the window responsive while the timer runs.
  • Work sessions last 25 minutes, short breaks 5 minutes, and every fourth break is a long 15 minute break.
  • Each finished session is saved to sessions.json, so progress survives a restart.
  • We tested the full cycle headless with 3 second sessions, and all checks passed.

What we build

We build a small desktop Pomodoro timer with a real window, buttons, and a progress bar. It shows the time left in large digits, marks each finished Pomodoro with a check, and moves between focus time and breaks on its own. Press Start once and the app runs the whole cycle: four work sessions, short breaks between them, and a long break at the end. Every finished session is written to a JSON file next to the script, so we can see how many Pomodoros we completed across days.

The full app is one file, about 160 lines, and it uses only the Python standard library. That is the point. A first desktop app should teach the GUI event loop and a little state management, not fight with package installs.

Prerequisites

We need Python 3.8 or newer. Tkinter ships with Python on Windows and macOS, and with most Linux installs. We check it with one command:

python3 -c "import tkinter; print(tkinter.TkVersion)"
Enter fullscreen mode Exit fullscreen mode

Our test machine runs Python 3.12.3 with Tkinter 8.6, and the command above prints 8.6. If the import fails on Linux, install the system package for Tkinter, for example python3-tk on Debian and Ubuntu, then try again. We also need a folder for the project:

mkdir pomodoro-timer
cd pomodoro-timer
Enter fullscreen mode Exit fullscreen mode

Step 1: Set the session lengths and format the time

We start pomodoro.py with imports, the three session lengths, and a helper that turns seconds into a clock display:

import json
import os
import tkinter as tk
from datetime import datetime
from tkinter import ttk

WORK_MIN = 25
SHORT_BREAK_MIN = 5
LONG_BREAK_MIN = 15
SESSIONS_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)),
                             "sessions.json")

def format_time(seconds):
    """Turn a second count into MM:SS, for example 1500 becomes 25:00."""
    minutes, seconds = divmod(seconds, 60)
    return f"{minutes:02d}:{seconds:02d}"
Enter fullscreen mode Exit fullscreen mode

Constants sit at the top on purpose. Changing the work session from 25 to 50 minutes is a one line edit, and the rest of the app reads the constants instead of repeating numbers. The format_time helper uses divmod, which returns the minutes and the leftover seconds in one call. We test it on its own before any window exists, because a wrong clock display is much easier to catch in a plain function than inside a running GUI.

Step 2: Build the window and the widgets

The PomodoroTimer class owns the window and all of its state. Its constructor takes the session lengths in seconds, with the minute constants as defaults, and then builds the interface:

class PomodoroTimer:
    def __init__(self, root, work_seconds=WORK_MIN * 60,
                 short_break_seconds=SHORT_BREAK_MIN * 60,
                 long_break_seconds=LONG_BREAK_MIN * 60):
        self.root = root
        self.work_seconds = work_seconds
        self.short_break_seconds = short_break_seconds
        self.long_break_seconds = long_break_seconds
        self.mode = "work"          # work, short_break, long_break
        self.time_left = self.work_seconds
        self.completed = 0          # finished work sessions
        self.running = False
        self.after_id = None
        self.build_ui()
        self.show_time()
Enter fullscreen mode Exit fullscreen mode

The constructor takes seconds rather than minutes for one practical reason: our test passes 3 second sessions so a full cycle finishes in seconds instead of two hours. Real use still gets the 25 minute default. The build_ui method adds a mode label, a large time label, a progress bar, a checkmark label, four buttons, and a status line. We use ttk widgets, the themed set from the Tkinter docs, because they match the look of the host system instead of the old flat Tk widgets.

def build_ui(self):
        self.root.title("Pomodoro Timer")
        self.root.geometry("360x340")
        self.root.resizable(False, False)

        self.mode_label = ttk.Label(self.root, text="Focus time",
                                    font=("Helvetica", 16))
        self.mode_label.pack(pady=(20, 5))

        self.time_label = ttk.Label(self.root, text="25:00",
                                    font=("Helvetica", 48, "bold"))
        self.time_label.pack(pady=5)

        self.progress = ttk.Progressbar(self.root, orient="horizontal",
                                        length=280, mode="determinate")
        self.progress.pack(pady=10)

        self.checks_label = ttk.Label(self.root, text="No sessions yet",
                                      font=("Helvetica", 12))
        self.checks_label.pack(pady=5)

        buttons = ttk.Frame(self.root)
        buttons.pack(pady=15)
        self.start_button = ttk.Button(buttons, text="Start",
                                       command=self.start)
        self.start_button.grid(row=0, column=0, padx=5)
        ttk.Button(buttons, text="Pause",
                   command=self.pause).grid(row=0, column=1, padx=5)
        ttk.Button(buttons, text="Reset",
                   command=self.reset).grid(row=0, column=2, padx=5)
        ttk.Button(buttons, text="Skip",
                   command=self.skip).grid(row=0, column=3, padx=5)

        self.status_label = ttk.Label(self.root, text="Ready when you are.",
                                      font=("Helvetica", 11))
        self.status_label.pack(pady=5)
Enter fullscreen mode Exit fullscreen mode

Each button points at a method with command=self.start and similar. The show_time method writes the current time into the big label and fills the progress bar from the share of the session that has passed.

Why does after() beat time.sleep() for a countdown?

This is the one idea that decides whether the app works or freezes. A first attempt at a countdown often looks like a loop with time.sleep(1). That loop blocks the Tkinter event loop, so the window cannot redraw, buttons cannot respond, and the time label never updates until the whole loop ends. The app looks dead for 25 minutes.

The Tkinter docs describe after() as the way to schedule a callback after a delay without blocking. Our tick method counts down one second, updates the display, and then asks the event loop to call it again in 1000 milliseconds. Between ticks the event loop is free, so clicks and redraws work normally:

def start(self):
        if self.running:
            return
        self.running = True
        self.status_label.config(text="Timer running.")
        self.tick()

    def tick(self):
        if not self.running:
            return
        if self.time_left > 0:
            self.time_left -= 1
            self.show_time()
            self.after_id = self.root.after(1000, self.tick)
        else:
            self.finish_session()
Enter fullscreen mode Exit fullscreen mode

Pause works by cancelling the scheduled call. Tkinter returns an id from every after() call, and after_cancel() removes that call from the queue. We store the id in self.after_id so Pause can find it:

def pause(self):
        self.running = False
        if self.after_id is not None:
            self.root.after_cancel(self.after_id)
            self.after_id = None
        self.status_label.config(text="Paused.")
Enter fullscreen mode Exit fullscreen mode

Reset stops the timer, returns to a fresh work session, and clears the running flag. Skip ends the current session at once and lets the normal finish logic decide what comes next.

Step 3: Switch sessions and count Pomodoros

When the countdown reaches zero, finish_session logs the session, updates the checkmarks, and picks the next mode. A finished work session adds one check. After every fourth work session the next break is the long one. A finished break always returns to focus time:

def finish_session(self):
        self.running = False
        self.after_id = None
        finished = self.mode
        self.log_session(finished)
        if finished == "work":
            self.completed += 1
            self.checks_label.config(
                text="Pomodoros done: " + "✓ " * self.completed)
            if self.completed % 4 == 0:
                self.mode = "long_break"
                self.time_left = self.long_break_seconds
                self.mode_label.config(text="Long break, well earned")
            else:
                self.mode = "short_break"
                self.time_left = self.short_break_seconds
                self.mode_label.config(text="Short break")
        else:
            self.mode = "work"
            self.time_left = self.work_seconds
            self.mode_label.config(text="Focus time")
        self.root.bell()
        self.show_time()
        self.status_label.config(text="Session saved to sessions.json.")
        # The next session starts on its own, so a break really is a
        # break and the user never has to babysit the timer.
        self.start()
Enter fullscreen mode Exit fullscreen mode

We made one deliberate choice here: the next session starts on its own. Many timer apps wait for another click, which means a break only starts when the user remembers to press Start. Auto start keeps the rhythm honest, and Pause is always there when life interrupts. The root.bell() call plays the system alert sound so the switch is heard as well as seen.

How does the app remember finished sessions?

Memory in this app is a plain JSON file, not a database. Each finished session appends one small record with its type, its length in minutes, and the time it ended. The file lives next to the script, so it survives closing the app and it is easy to read by hand:

def log_session(self, kind):
        entry = {
            "type": kind,
            "minutes": self.session_seconds() // 60,
            "finished_at": datetime.now().isoformat(timespec="seconds"),
        }
        history = []
        if os.path.exists(SESSIONS_FILE):
            with open(SESSIONS_FILE, "r", encoding="utf-8") as f:
                history = json.load(f)
        history.append(entry)
        with open(SESSIONS_FILE, "w", encoding="utf-8") as f:
            json.dump(history, f, indent=2)
Enter fullscreen mode Exit fullscreen mode

JSON is the right store at this size. A database would add a dependency and a setup step for a list that grows by a few records a day. If the history ever grows past a few thousand entries, that is the moment to switch to SQLite, and the log_session method is the only place that would change.

Step 4: Run it

Two lines at the bottom of the file launch the app:

def main():
    root = tk.Tk()
    PomodoroTimer(root)
    root.mainloop()

if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

We run it with:

python3 pomodoro.py
Enter fullscreen mode Exit fullscreen mode

The window opens showing 25:00 and the text "Focus time". Press Start and the digits count down, the progress bar fills, and after 25 minutes the label changes to "Short break" and a check appears. Four Pomodoros later the label reads "Long break, well earned" and the break lasts 15 minutes.

Step 5: Test the whole cycle in seconds

A 25 minute timer is awkward to test by hand, so we wrote a test that builds the real window with 3 second work sessions and 2 second breaks, then drives the Tk event loop directly. The test runs under a virtual display, since our test machine has no screen:

xvfb-run -a python3 test_pomodoro.py
Enter fullscreen mode Exit fullscreen mode

Testing caught two real bugs before this article was written. First, fractional minute values made format_time crash on a float, so the constructor now takes seconds. Second, a finished session did not start the next one, so breaks never began until the user pressed Start again. Both fixes are in the code above. The full test run prints:

format_time: 1500 -> 25:00, 65 -> 01:05, 0 -> 00:00
initial display: 00:03, mode: work
work finished -> short break, completed = 1
sessions.json after work: [{'type': 'work', 'minutes': 0,
  'finished_at': '2026-11-20T02:52:50'}]
break finished -> back to work
pause works: time_left stayed at 2
reset works: mode work, 00:03, stopped
skip works, sessions.json now has 3 entries
4th Pomodoro -> long break, counting down from 00:03
ALL TESTS PASSED
Enter fullscreen mode Exit fullscreen mode

The test log shows "minutes": 0 because the test sessions lasted 3 seconds. With real 25 minute sessions the same entry reads "minutes": 25, since the value comes from the session length in the code, not from a stopwatch. The test also verified Pause really stops the countdown, Reset returns to a fresh work session, Skip jumps to the next session, and the fourth Pomodoro triggers the long break.

What to try next

First, add a task name field so each Pomodoro records what it was spent on, then read sessions.json back at startup and show today's total on the window. Second, add a small settings row with spinboxes for the three durations, so the lengths change without editing code. Third, play a short sound file instead of the system bell when a session ends, and add a tray notification for users who keep the window minimised.


Originally published on LogicStack. Run the code examples right in your browser with our free interactive Python and SQL playgrounds — no setup, no sign-up.

Top comments (1)

Collapse
 
fizanahmed profile image
fizan ahmed •

This is a really clear walkthrough for a first Tkinter project. I like that it stays to the standard library, and the explanation of why after() beats time.sleep() is the part I needed most. A frozen window is exactly what I ran into on my first timer attempt. Saving sessions to JSON is also a nice touch, because it makes the app feel real without adding a database. The task name idea at the end is a good next step. Thanks for sharing the testing approach with short sessions too.