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

FAQ #

Why does my countdown timer not stop? #

Usually the counter is not being decreased inside the loop, or the loop condition is wrong.

Why do I need `import time`? #

Because sleep() is part of Python’s time module. It is not available automatically by itself.

Why does `input()` cause an error? #

input() returns text. You usually need int(input(...)) if you want to count down from a number.

Can I make the timer use minutes and seconds? #

Yes. That is a good next step after the simple version works.