Python Countdown Timer Example

A countdown timer is a great beginner Python project. It helps you practice variables, loops, and pauses with sleep().

This example shows how to build a simple countdown timer that:

counts down one number at a time
waits 1 second between numbers
prints a final message when it finishes

Start with the basic version first. Once it works, you can safely change the starting number or add user input.

Quick example

import time

seconds = 5

while seconds > 0:
    print(seconds)
    time.sleep(1)
    seconds -= 1

print("Time's up!")

This is the fastest working version. It counts down from 5 to 1, waits 1 second between numbers, then prints a finish message.

What this example builds

This script creates:

A countdown that prints one number at a time
A pause of 1 second between each number
A final message when the countdown ends

It is a good first project for practicing:

variables
while loops
the time.sleep() function

Before you start

You do not need much to follow this example.

It helps if you already know:

basic variables
the idea of a while loop, or are willing to follow one simple loop
how to run a Python file

You also need Python installed.

This example uses Python’s built-in time module. You can learn more in this Python time module overview.

Simple countdown timer example

Here is the full script again:

import time

seconds = 5

while seconds > 0:
    print(seconds)
    time.sleep(1)
    seconds -= 1

print("Time's up!")

This version works like this:

Start with a number stored in a variable
Keep looping while the number is greater than 0
Print the current number
Pause for 1 second
Subtract 1
Print a final message after the loop ends

How the code works

Let’s go through it line by line.

`import time`

import time

This gives your program access to the time module.

Without this line, time.sleep(1) will not work.

`seconds = 5`

seconds = 5

This sets the starting value for the countdown.

If you change it to 10, the timer will count down from 10 instead.

`while seconds > 0`

while seconds > 0:

This means:

keep running the loop
only while seconds is greater than 0

When seconds becomes 0, the loop stops.

If you are new to loops, see Python while loops explained.

`print(seconds)`

print(seconds)

This shows the current countdown number on the screen.

`time.sleep(1)`

time.sleep(1)

This pauses the program for 1 second.

It does not print anything by itself. It only makes the program wait.

`seconds -= 1`

seconds -= 1

This reduces seconds by 1 each time through the loop.

It is the same as writing:

seconds = seconds - 1

This line is very important. Without it, the countdown would never move toward 0.

Final message

print("Time's up!")

This line runs only after the loop finishes.

That is why you see the message at the end, not during the countdown.

Expected output

When you run the script, you should see something like this:

5
4
3
2
1
Time's up!

There will be a 1-second pause between each number.

Version that gets user input

You can also ask the user for the starting number.

import time

seconds = int(input("Enter the number of seconds: "))

while seconds > 0:
    print(seconds)
    time.sleep(1)
    seconds -= 1

print("Time's up!")

How this version is different

input() asks the user to type something
input() returns text
int() converts that text to a whole number

So if the user types 5, Python turns it into the number 5.

If you want to learn more, see:

Important note about bad input

If the user types something like hello instead of a number, this line will fail:

seconds = int(input("Enter the number of seconds: "))

That raises a ValueError.

Example:

seconds = int(input("Enter the number of seconds: "))

If the input is not a valid whole number, read how to fix ValueError: invalid literal for int() with base 10.

Small improvements beginners can try

Once the basic version works, try small changes like these:

Change the finish message
Start from a different number
Add a message before the countdown starts
Wrap the code in a function
Build a later version that shows minutes and seconds

Example with a start message:

import time

seconds = 5

print("Starting countdown...")

while seconds > 0:
    print(seconds)
    time.sleep(1)
    seconds -= 1

print("Done!")

Example wrapped in a function:

import time

def countdown(seconds):
    while seconds > 0:
        print(seconds)
        time.sleep(1)
        seconds -= 1
    print("Time's up!")

countdown(5)

Common beginner mistakes

These are the most common problems with simple countdown timers.

Forgetting to import `time`

If you use time.sleep(1) without importing time, Python will raise a NameError.

Wrong:

seconds = 5

while seconds > 0:
    print(seconds)
    time.sleep(1)
    seconds -= 1

Fix:

import time

Using `input()` without `int()`

input() returns text, not a number.

Wrong:

seconds = input("Enter seconds: ")

If you try to compare that text with numbers in a loop, your program may fail or behave incorrectly.

Fix:

seconds = int(input("Enter seconds: "))

Forgetting to decrease the counter

If you leave out this line:

seconds -= 1

the value never changes, so the loop may run forever.

Using the wrong loop condition

This line controls when the countdown stops:

while seconds > 0:

If the condition is wrong, the timer may stop too early or never stop.

Expecting `sleep()` to print something

time.sleep(1) only pauses the program. It does not display output.

Debugging tips

If your countdown is not working, try these simple checks.

Print the counter value each loop

print(seconds)

This helps you confirm that the value is changing.

Print a message inside the loop

print("loop running")

If this prints forever, your loop condition or counter update is probably wrong.

Check the type of user input

print(type(user_input))

This helps when you are working with input() and want to see whether you still have text instead of a number.

Problems and likely causes

Common causes include:

NameError because time was used without import time
ValueError when converting non-number text with int()
an infinite loop because the counter is never decreased
the wrong countdown length because the starting value is not what the user expected

Next steps

After you get this version working, good next steps are:

learn more about Python while loops
practice with input() and int()
try a timer that uses minutes and seconds
build another small script like a Python timer script example or a Python stopwatch example