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)" 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 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}" 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() 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) 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() 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.") 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() 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) 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() We run it with:
python3 pomodoro.py 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 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 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.
