A Dice Rolling Simulator is a small project, but it teaches the same building blocks you use in real GUI applications: window setup, layout, event handling, shared state, and safe UI updates. In this tutorial, you will build a clean Tkinter app that shows a large dice face (⚀ ⚁ ⚂ ⚃ ⚄ ⚅), displays the result text, tracks the total number of rolls, and plays a short rolling animation before landing on the final value.
You only need Python 3.x (regular Python or Anaconda). This project uses only built-in modules:
tkinter and tkinter.ttk for the GUI widgetstkinter.messagebox for error and confirmation dialogsrandom for generating dice valuesDiceRollingSimulatordice_rolling_simulator.pyThis entire tutorial builds one file. By the end, your file will contain imports, one class, and a small main() launcher.
Normal Python (CMD/Terminal):
cd path/to/DiceRollingSimulator
python dice_rolling_simulator.py
Anaconda Prompt (if you installed Anaconda):
cd path/to/DiceRollingSimulator
python dice_rolling_simulator.py
Jupyter Notebook note:
Tkinter runs best from a .py file. If you use Jupyter anyway, paste the full file into one cell and run once. If the window becomes unresponsive, restart the kernel and run again.
Import libraries:
import tkinter as tk
from tkinter import ttk, messagebox
import random
Code language: JavaScript (javascript)This is the first code in the file, so it doesn’t depend on anything before it. Each line has a specific role:
import tkinter as tk loads Tkinter and gives it the short alias tk. This matters because later you’ll write tk.Tk (the main window class), tk.StringVar (for auto-updating label text), and tk.TclError (for theme fallback).from tkinter import ttk, messagebox brings in:
ttk for modern-looking widgets like ttk.Frame, ttk.Label, ttk.Button.messagebox for popups like error dialogs and exit confirmation.import random is needed because the dice roll is generated using random.randint(1, 6).This connects forward because the very next step creates a class that inherits from tk.Tk, so the import alias tk must already exist.
add this directly below the imports:
class DiceRollingApp(tk.Tk):
"""A clean, beginner-friendly Dice Rolling Simulator using Tkinter."""
Code language: CSS (css)Here’s what each line is doing and why it matters:
class DiceRollingApp(tk.Tk): creates a new class named DiceRollingApp. The (tk.Tk) part is critical: it means this class inherits from Tkinter’s main window, so the class itself is the window."""...""") is a description string stored on the class. It doesn’t affect behavior, but it documents what the class represents.This connects backward to Step 1 because tk.Tk only exists because you imported tkinter as tk. This connects forward because once the class block starts, the next snippet must add __init__() inside this class.
__init__() (Inside the Class)Paste this inside the same class, directly under the docstring (4-space indentation):
def __init__(self):
super().__init__()
# ---------- Window setup ----------
self.title("Dice Rolling Simulator")
self.minsize(420, 320)
self.resizable(False, False)
Code language: PHP (php)This snippet is the foundation of the entire app. It connects backward because it must be placed inside the class started in Step 2. It connects forward because later steps will keep adding more lines inside this same __init__() method.
Line-by-line, here’s what’s happening:
def __init__(self): declares the initializer method. This runs automatically when you create DiceRollingApp() in the main() function later.super().__init__() calls the parent (tk.Tk) initializer. Without this line, the actual window will not be properly created, and many Tkinter features won’t work.# ---------- Window setup ---------- is a visual separator comment. It doesn’t run, but it helps readers understand the section.self.title("Dice Rolling Simulator") sets the title shown in the window’s title bar.self.minsize(420, 320) sets a minimum size so the UI never becomes too cramped.self.resizable(False, False) disables resizing in both directions, which keeps the layout stable for beginners.Next, the window needs shared “state” variables like dice faces and roll counters, so the next step extends __init__().
__init__()Add this immediately after the previous resizable(...) line (still inside __init__()):
# ---------- App state ----------
self.dice_faces = {
1: "⚀",
2: "⚁",
3: "⚂",
4: "⚃",
5: "⚄",
6: "⚅",
}
self.total_rolls = 0
self.is_animating = False
self._after_id = None
Code language: PHP (php)This snippet connects backward because it must stay inside __init__()—the indentation level (8 spaces) tells Python these lines are part of the initializer. It connects forward because later methods will read these values to update the UI and run the animation safely.
Line-by-line explanation:
# ---------- App state ---------- is another section divider comment.self.dice_faces = { ... } creates a dictionary mapping numbers 1–6 to Unicode dice symbols. This is the core trick that lets you show dice faces without images.
1, 2, …) is the rolled value."⚀", "⚁", …) is the character shown on screen.6: "⚅", is valid Python and makes it easier to edit later.self.total_rolls = 0 starts the roll counter at zero. Every successful roll will increment this.self.is_animating = False tracks whether an animation is currently running. This prevents double-click bugs (multiple animations overlapping).self._after_id = None will store the callback id returned by Tkinter’s after() scheduling. This matters because reset must be able to cancel a scheduled animation step.Next, you’ll add animation configuration variables that control how long the rolling effect runs.
__init__())Add this right after _after_id = None (still inside __init__()):
# Animation configuration (tweak these for faster/slower animation)
self.animation_duration_ms = 800 # total animation time (~0.8 sec)
self.animation_interval_ms = 80 # update every 80ms
self._steps_remaining = 0
self._final_value = None
Code language: PHP (php)This snippet connects backward because it extends the “state” idea from the previous step, still inside the initializer. It connects forward because the animation methods (start_animation() and _animate_step()) will rely on these values.
Line-by-line explanation:
self.animation_duration_ms = 800 means the total rolling animation should last about 800 milliseconds.self.animation_interval_ms = 80 means the dice face will change every 80 milliseconds during the animation.self._steps_remaining = 0 will later be set to a countdown number so _animate_step() knows when to stop.self._final_value = None will later store the final dice number (1–6) chosen once at the start of the animation.Next, you’ll style the app using ttk themes so the buttons look clean and consistent.
__init__())Paste this right after _final_value = None (still inside __init__()):
# ---------- Styling (ttk) ----------
self.style = ttk.Style(self)
try:
# "clam" looks clean across many systems; safe fallback if unavailable
self.style.theme_use("clam")
except tk.TclError:
pass
self.style.configure("TFrame", padding=0)
self.style.configure("TButton", padding=6)
Code language: PHP (php)This snippet connects backward because ttk.Style is only available thanks to Step 1 imports. It connects forward because the next step will build the UI, and those UI widgets will benefit from the styling choices.
Line-by-line explanation:
# ---------- Styling (ttk) ---------- separates styling from state.self.style = ttk.Style(self) creates a style manager attached to this window.try: begins a safe block—some systems may not support every theme.clam is chosen.self.style.theme_use("clam") tries to apply the “clam” theme.except tk.TclError: catches the error Tkinter raises if the theme isn’t available.pass means “do nothing,” so the program continues with the default theme instead of crashing.self.style.configure("TFrame", padding=0) sets a default style for ttk Frames.self.style.configure("TButton", padding=6) adds comfortable padding to all ttk Buttons.Next, the initializer must create widgets and connect events, so you’ll add the build calls.
__init__())Add this directly after the style configuration lines (still inside __init__()):
# ---------- Build UI ----------
self._build_ui()
self._bind_events()
# Default state
self.reset()
Code language: PHP (php)This snippet is the “bridge” between setup and functionality. It connects backward because the app state and styles must exist before you build widgets. It connects forward because _build_ui(), _bind_events(), and reset() do not exist yet—you will define them as methods inside the same class in upcoming steps.
Line-by-line explanation:
self._build_ui() will create labels, buttons, and text variables.self._bind_events() will connect Enter key presses and the window close button to your methods.self.reset() is called after widgets exist so the dice display and label text are set to a clean starting state.At this point, your __init__() is complete. Next, you must define _build_ui() because __init__() now calls it.
_build_ui() (Inside the Same Class)Add this below ********************__init__(), still inside the class (4-space indentation):
def _build_ui(self):
"""Create and place all widgets."""
container = ttk.Frame(self, padding=16)
container.grid(row=0, column=0, sticky="nsew")
# Make the container expand nicely
self.grid_rowconfigure(0, weight=1)
self.grid_columnconfigure(0, weight=1)
# Title label
title = ttk.Label(container, text="Dice Rolling Simulator", font=("Segoe UI", 16, "bold"))
title.grid(row=0, column=0, columnspan=3, pady=(0, 14))
# Dice display (large and centered)
self.dice_label = ttk.Label(container, text="—", font=("Segoe UI Symbol", 84))
self.dice_label.grid(row=1, column=0, columnspan=3, pady=(0, 10))
# Result section
self.result_var = tk.StringVar(value="Click Roll Dice to start.")
self.count_var = tk.StringVar(value="Total Rolls: 0")
result_label = ttk.Label(container, textvariable=self.result_var, font=("Segoe UI", 12))
result_label.grid(row=2, column=0, columnspan=3, pady=(0, 4))
count_label = ttk.Label(container, textvariable=self.count_var, font=("Segoe UI", 11))
count_label.grid(row=3, column=0, columnspan=3, pady=(0, 14))
# Controls section
self.roll_btn = ttk.Button(container, text="Roll Dice", command=self.on_roll_request)
self.reset_btn = ttk.Button(container, text="Clear/Reset", command=self.reset)
self.exit_btn = ttk.Button(container, text="Exit", command=self.on_exit)
self.roll_btn.grid(row=4, column=0, sticky="ew", padx=(0, 8))
self.reset_btn.grid(row=4, column=1, sticky="ew", padx=8)
self.exit_btn.grid(row=4, column=2, sticky="ew", padx=(8, 0))
# Make buttons evenly sized
container.grid_columnconfigure(0, weight=1)
container.grid_columnconfigure(1, weight=1)
container.grid_columnconfigure(2, weight=1)
# Give initial focus to the Roll button for keyboard convenience
self.roll_btn.focus_set()
Code language: PHP (php)This snippet connects backward because __init__() calls _build_ui() (Step 7). It connects forward because it references methods that don’t exist yet (on_roll_request, reset, on_exit)—those methods will be added later inside the same class.
Line-by-line explanation:
def _build_ui(self): creates a private helper method (underscore naming) used only inside the class.container = ttk.Frame(self, padding=16) creates a main “wrapper” frame with padding.container.grid(...) places that frame in the main window using grid.self.grid_rowconfigure(0, weight=1) and self.grid_columnconfigure(0, weight=1) make the container able to grow properly inside the window.Title:
title = ttk.Label(...) creates a heading label placed inside container.title.grid(... columnspan=3 ...) makes the label span 3 columns so it aligns with the 3-button layout below.Dice display:
self.dice_label = ttk.Label(...) creates the big dice label and stores it on self so other methods (animation/reset) can change it.self.dice_label.grid(...) places it on row 1 across 3 columns.Result text variables:
self.result_var = tk.StringVar(...) creates a Tkinter variable that can update a label automatically.self.count_var = tk.StringVar(...) does the same for roll count.Result labels:
result_label = ttk.Label(... textvariable=self.result_var ...) links the label’s text to the variable.result_label.grid(...) places it below the dice.count_label = ttk.Label(... textvariable=self.count_var ...) links roll count display.count_label.grid(...) places it below the result line.Buttons:
self.roll_btn = ttk.Button(... command=self.on_roll_request) wires the button click to on_roll_request().self.reset_btn = ttk.Button(... command=self.reset) wires Reset to the reset() method.self.exit_btn = ttk.Button(... command=self.on_exit) wires Exit to the on_exit() method.Button placement:
.grid(...) places a button in row 4, columns 0–2.sticky="ew" makes each button stretch left-to-right.padx=(...) adds spacing between buttons.Column sizing:
container.grid_columnconfigure(... weight=1) for columns 0, 1, 2 ensures the 3 columns share width evenly.Focus:
self.roll_btn.focus_set() makes keyboard usage smoother by focusing the Roll button at start.Next, you must define _bind_events() because __init__() calls it right after _build_ui().
_bind_events() (Inside the Same Class)Add this below _build_ui() (still inside the class):
def _bind_events(self):
"""Keyboard and window events."""
self.bind("<Return>", lambda event: self.on_roll_request())
self.protocol("WM_DELETE_WINDOW", self.on_exit)
Code language: PHP (php)This snippet connects backward to Step 7 because __init__() calls _bind_events(). It connects forward because now the Enter key and window close button depend on on_roll_request() and on_exit(), which you will add in the next steps.
Line-by-line explanation:
def _bind_events(self): defines another class helper method.self.bind("<Return>", ...) binds the Enter key to a function.lambda event: self.on_roll_request() exists because Tkinter passes an event object automatically; the lambda accepts it and calls your method without changing its signature.self.protocol("WM_DELETE_WINDOW", self.on_exit) replaces the default close behavior with your own on_exit() confirmation logic.Next, you need to add the “core action” methods, starting with on_roll_request().
on_roll_request() (Inside the Same Class)Add this below _bind_events():
# ---------- Core actions ----------
def on_roll_request(self):
"""Handle Roll requests safely (ignores clicks during animation)."""
try:
if self.is_animating:
return # safely ignore extra clicks
self.start_animation()
except Exception as exc:
# Safety net: show the error but never crash
messagebox.showerror("Error", f"Something went wrong while rolling.
Details: {exc}")
Code language: PHP (php)This snippet connects backward because:
_build_ui() uses command=self.on_roll_request._bind_events() also calls this method.It connects forward because it calls self.start_animation(), which does not exist yet—you will add it next.
Line-by-line explanation:
# ---------- Core actions ---------- is a visual section divider inside the class.def on_roll_request(self): defines the method used when the user requests a roll.try: protects the GUI from crashing due to unexpected errors.if self.is_animating: checks the shared state created in __init__().return # safely ignore extra clicks exits early if an animation is already running.self.start_animation() begins the rolling animation; the roll result will be finalized after animation.except Exception as exc: catches any unexpected exception.messagebox.showerror(...) shows an error dialog with the exception details, keeping the app alive.Next, you’ll define start_animation() because this method calls it.
start_animation() (Inside the Same Class)Add this below on_roll_request():
def start_animation(self):
"""Start a short roll animation and land on a final dice value."""
self.is_animating = True
self.roll_btn.state(["disabled"]) # prevent rapid clicks causing multiple animations
# Decide final dice value once (so animation always ends on this value)
self._final_value = random.randint(1, 6)
# Convert duration to number of steps
self._steps_remaining = max(1, self.animation_duration_ms // self.animation_interval_ms)
# Start stepping through random faces
self._animate_step()
Code language: PHP (php)This snippet connects backward because on_roll_request() calls start_animation(). It connects forward because it calls _animate_step() repeatedly using after(), which you’ll implement next.
Line-by-line explanation:
def start_animation(self): creates the method that begins the rolling effect.self.is_animating = True switches the app into “animation mode,” so new roll requests are blocked.self.roll_btn.state(["disabled"]) disables the Roll button so the UI itself prevents spam clicks.self._final_value = random.randint(1, 6) stores the final roll number in shared state.self._steps_remaining = max(1, ...) calculates how many frames are needed (duration divided by interval), but never allows 0 steps.self._animate_step() calls the first animation frame method.Next, you’ll add _animate_step() because the animation cannot proceed without it.
_animate_step() (Inside the Same Class)Add this below start_animation():
def _animate_step(self):
"""One animation step: show a random face, then schedule the next step."""
try:
if self._steps_remaining > 0:
# Show a random face during animation
temp_value = random.randint(1, 6)
self._set_dice_face(temp_value)
self.result_var.set("Rolling...")
self._steps_remaining -= 1
self._after_id = self.after(self.animation_interval_ms, self._animate_step)
else:
# Animation finished: commit final value
self._after_id = None
self.is_animating = False
self.roll_btn.state(["!disabled"])
self.roll_once(self._final_value)
except Exception as exc:
# If anything unexpected happens, restore UI to safe state
self.is_animating = False
self.roll_btn.state(["!disabled"])
self._after_id = None
messagebox.showerror("Error", f"Animation error.
Details: {exc}")
Code language: PHP (php)This snippet connects backward because start_animation() calls _animate_step() to begin the loop. It connects forward because it uses two methods that don’t exist yet:
_set_dice_face() to update the dice symbol during rolling,roll_once() to finalize the roll and update counters.Line-by-line explanation:
def _animate_step(self): defines one frame of the animation loop.try: protects the GUI from crashing during animation.Animation phase:
if self._steps_remaining > 0: checks whether more frames are needed.temp_value = random.randint(1, 6) generates a temporary face number for this frame.self._set_dice_face(temp_value) updates the big dice display (method comes later).self.result_var.set("Rolling...") updates the message label while the dice is “spinning.”Scheduling the next frame:
self._steps_remaining -= 1 counts down one step.self._after_id = self.after(self.animation_interval_ms, self._animate_step) schedules the next frame after the interval and stores the callback id. Storing it is critical because reset() must cancel it if the user resets mid-animation.Finalization phase:
else: runs when steps reach zero.self._after_id = None clears the stored callback id because nothing is scheduled now.self.is_animating = False exits animation mode.self.roll_btn.state(["!disabled"]) re-enables the Roll button.self.roll_once(self._final_value) performs one completed roll using the final value selected in start_animation().Error handling phase:
except Exception as exc: catches unexpected errors.self.is_animating = False ensures the app doesn’t get stuck in “animating.”self.roll_btn.state(["!disabled"]) re-enables rolling.self._after_id = None clears any scheduled id reference.messagebox.showerror(...) informs the user.Next, you’ll add roll_once() because _animate_step() calls it when the animation completes.
roll_once() (Inside the Same Class)Add this below _animate_step():
def roll_once(self, value=None):
"""Perform one completed roll (increments count and updates UI)."""
if value is None:
value = random.randint(1, 6)
self.total_rolls += 1
self.update_ui(value)
Code language: PHP (php)This snippet connects backward because _animate_step() finishes by calling roll_once(self._final_value). It connects forward because it calls update_ui(), which you will add next.
Line-by-line explanation:
def roll_once(self, value=None): defines a method that represents one completed roll.if value is None: allows the method to be used without animation in the future (or if you ever add a “instant roll” mode).value = random.randint(1, 6) chooses a value if none is provided.self.total_rolls += 1 increments the counter created in __init__().self.update_ui(value) updates the visible dice face, result message, and roll count.Next, you’ll define update_ui() because this method depends on it.
update_ui() (Inside the Same Class)Add this below roll_once():
# ---------- UI helpers ----------
def update_ui(self, value: int):
"""Update dice face, result text, and roll count."""
self._set_dice_face(value)
self.result_var.set(f"You rolled: {value}")
self.count_var.set(f"Total Rolls: {self.total_rolls}")
Code language: PHP (php)This snippet connects backward because roll_once() calls update_ui(value). It connects forward because it calls _set_dice_face(), which you will add next.
Line-by-line explanation:
# ---------- UI helpers ---------- starts a new internal section for methods that only update the UI.def update_ui(self, value: int): defines a helper that updates all display parts in one place.self._set_dice_face(value) updates the big dice symbol.self.result_var.set(...) sets the message label to show the rolled number.self.count_var.set(...) updates the roll count label using the shared self.total_rolls value.Next, you must implement _set_dice_face() because both animation and final updates depend on it.
_set_dice_face() (Inside the Same Class)Paste this below update_ui():
def _set_dice_face(self, value: int):
"""Set the dice label to the Unicode face for the given value."""
face = self.dice_faces.get(value, "—")
self.dice_label.config(text=face)
Code language: PHP (php)This snippet connects backward because:
_animate_step() calls _set_dice_face(temp_value) repeatedly,update_ui() calls _set_dice_face(value) for the final display.It connects forward because now reset logic can safely set the dice label, and other UI methods can rely on this mapping.
Line-by-line explanation:
def _set_dice_face(self, value: int): defines a small method dedicated to updating the dice display.face = self.dice_faces.get(value, "—") looks up the Unicode symbol from the dictionary created in __init__(). If an invalid value somehow appears, it uses the neutral dash ("—").self.dice_label.config(text=face) changes the label widget created in _build_ui() to show the selected face.Next, you’ll add reset() because __init__() calls reset() (Step 7) and the Reset button also uses it.
reset() (Inside the Same Class)It should below _set_dice_face():
def reset(self):
"""Reset the app to its default (neutral) state."""
try:
# If an animation is in progress, cancel its scheduled callbacks safely
if self._after_id is not None:
self.after_cancel(self._after_id)
self._after_id = None
self.is_animating = False
self.roll_btn.state(["!disabled"])
self.total_rolls = 0
self.dice_label.config(text="—")
self.result_var.set("Click Roll Dice to start.")
self.count_var.set("Total Rolls: 0")
self.roll_btn.focus_set()
except Exception as exc:
messagebox.showerror("Error", f"Reset failed.
Details: {exc}")
Code language: PHP (php)This snippet connects backward because:
__init__() calls self.reset() after building the UI,command=self.reset.It connects forward because it makes the app stable: even if the user clicks Reset while the dice is rolling, the scheduled animation is canceled cleanly.
Line-by-line explanation:
def reset(self): defines the reset behavior.try: protects the reset action from crashing the GUI.Cancel scheduled animation:
if self._after_id is not None: checks if an animation frame is scheduled.self.after_cancel(self._after_id) cancels that scheduled callback.self._after_id = None clears the stored id so the state is consistent.Restore interaction:
self.is_animating = False ensures the app leaves animation mode.self.roll_btn.state(["!disabled"]) re-enables the Roll button.Reset counters and UI:
self.total_rolls = 0 resets the roll count.self.dice_label.config(text="—") restores the neutral dice face.self.result_var.set(...) restores the default message.self.count_var.set(...) resets the label text.Focus:
self.roll_btn.focus_set() makes Enter key usage smooth again.Error handling:
except Exception as exc: catches unexpected issues.messagebox.showerror(...) shows a friendly popup.Next, you’ll implement on_exit() because both the Exit button and the window close protocol depend on it.
on_exit() (Inside the Same Class)Add this below reset():
def on_exit(self):
"""Confirm and close the application safely."""
try:
if messagebox.askokcancel("Exit", "Do you want to exit the Dice Rolling Simulator?"):
self.destroy()
except Exception:
# Even if messagebox fails (rare), allow the window to close
self.destroy()
Code language: PHP (php)This snippet connects backward because:
command=self.on_exit._bind_events() set WM_DELETE_WINDOW to call self.on_exit.It connects forward because after this, your class has all methods needed to run safely, and the only remaining part is adding the file entry point (main()).
Line-by-line explanation:
def on_exit(self): defines the exit behavior.try: protects the close flow.if messagebox.askokcancel(...): shows a confirmation dialog with OK/Cancel.self.destroy() closes the Tkinter window and ends the GUI.except Exception: handles rare failures (for example, if messagebox cannot display).self.destroy() ensures the window still closes.Next, you’ll add main() and the __name__ guard outside the class so the program can actually start.
main() and the __name__ Guard (Outside the Class)Now scroll to the bottom of the file and paste this with no class indentation:
def main():
app = DiceRollingApp()
app.mainloop()
if __name__ == "__main__":
main()
Code language: JavaScript (javascript)This snippet connects backward because it creates an instance of the class you built. It also explains why earlier snippets mattered:
def main(): defines a clean entry function at the file level.app = DiceRollingApp() creates the window. This triggers __init__(), which:
app.mainloop() starts Tkinter’s event loop. Without this, the window would appear and immediately close.if __name__ == "__main__": ensures the app runs only when this file is executed directly (not when imported).DiceRollingApp(tk.Tk) begins__init__() (window setup → app state → animation settings → ttk styling → build calls → reset)_build_ui()_bind_events()on_roll_request()start_animation()_animate_step()roll_once()update_ui()_set_dice_face()reset()on_exit()main() and the __name__ guardIf your file matches that structure and indentation, you have built the entire Dice Rolling Simulator by copying code exactly in the order shown.
When you run the program: