Python time Module Overview

The time module is a built-in Python module for simple time-related tasks.

Beginners usually use it for:

getting the current timestamp
pausing a program
measuring how long code takes to run

It is a good starting point when you need something simple. If you need readable dates, calendar values, or date math, the datetime module overview is usually a better fit.

Quick example

import time

print(time.time())
print("Waiting...")
time.sleep(2)
print("Done")

What this does:

time.time() gets the current Unix timestamp
time.sleep(2) pauses the whole program for 2 seconds

Example output:

1712345678.123456
Waiting...
Done

What the time module is

The time module is built into Python, so you do not need to install anything.

It helps with:

timestamps
delays
simple timing tasks

This makes it useful when you want to:

pause code for a short time
measure how long something takes
get a numeric current time value

The time module is different from datetime.

time is better for delays and simple timestamps
datetime is better for readable dates like year, month, and day

When to use the time module

Use the time module when you need simple time features.

Common cases:

Pause a program with time.sleep()
Get the current timestamp with time.time()
Measure how long code takes to run

Use datetime instead when you need:

readable dates
year, month, and day values
date calculations

Functions beginners should know first

Here are the most useful time module functions to learn first.

`time.time()`

Returns the current time as the number of seconds since the Unix epoch.

import time

current_timestamp = time.time()
print(current_timestamp)

This returns a float, not a formatted date string.

`time.sleep(seconds)`

Pauses the whole program for the number of seconds you give it.

import time

print("Start")
time.sleep(1)
print("One second later")

You can also use decimal values:

import time

time.sleep(0.5)
print("Half a second passed")

`time.ctime()`

Turns a timestamp into a readable string.

import time

timestamp = time.time()
print(time.ctime(timestamp))

Example output:

Fri Apr  5 12:34:56 2024

`time.localtime()`

Converts a timestamp into a structured local time value.

import time

current_time = time.localtime()
print(current_time)
print(current_time.tm_year)
print(current_time.tm_mon)
print(current_time.tm_mday)

This is useful when you want parts of the local date and time.

`time.strftime()`

Formats a time value as text.

import time

current_time = time.localtime()
formatted = time.strftime("%Y-%m-%d %H:%M:%S", current_time)
print(formatted)

Example output:

2024-04-05 12:34:56

Simple example flow

A common beginner workflow looks like this:

Import the module with import time
Get the current timestamp with time.time()
Pause execution with time.sleep()
Format the output only if you need readable text

Example:

import time

start = time.time()
print("Start timestamp:", start)

time.sleep(2)

end = time.time()
print("End timestamp:", end)

print("Readable end time:", time.ctime(end))

This example:

gets a start timestamp
waits 2 seconds
gets an end timestamp
shows the end time in a readable format

Common beginner use cases

The time module is often used for small, practical tasks.

Adding a delay in a script

import time

print("Loading...")
time.sleep(2)
print("Finished")

Timing how long a task takes

For a step-by-step guide, see how to measure execution time in Python.

import time

start = time.time()

for i in range(3):
    print("Working...")
    time.sleep(1)

end = time.time()

print("Duration:", end - start, "seconds")

Creating a simple countdown or timer

For a full walkthrough, see how to create a countdown timer in Python.

import time

for number in range(3, 0, -1):
    print(number)
    time.sleep(1)

print("Go!")

Printing the current timestamp for logs

import time

print("Log time:", time.time())

time module vs datetime module

Beginners often wonder which module to use.

Use time when you need:

delays
simple timestamps
basic timing

Use datetime when you need:

readable dates
year, month, and day values
date arithmetic

A simple rule:

start with time.sleep() and time.time() for basic tasks
move to datetime for date display and date math

Common mistakes

Here are some common beginner problems when using time.

Forgetting to import `time`

This causes a NameError.

print(time.time())

Fix:

import time

print(time.time())

Passing a string to `time.sleep()`

This will fail because sleep() expects a number.

import time

time.sleep("2")

Fix:

import time

time.sleep(2)

Expecting `time.time()` to return a readable date

time.time() returns a numeric Unix timestamp.

import time

print(time.time())

If you want readable text, use time.ctime() or time.strftime().

import time

print(time.ctime())

Using `time` when `datetime` would be easier

If you need values like year, month, and day in a clean object, the datetime module overview is usually easier to work with.

Thinking `sleep()` pauses only one line

time.sleep() pauses the whole program before it moves to the next line.

import time

print("Before")
time.sleep(2)
print("After")

Useful commands to test the module

These commands let you quickly check that the module works in your Python installation.

python --version
python -c "import time; print(time.time())"
python -c "import time; time.sleep(1); print('done')"
python -c "import time; print(time.ctime())"

FAQ

Is the time module built into Python?

Yes. You can use it with import time and do not need to install anything.

What does time.sleep() do?

It pauses the whole program for the number of seconds you give it.

What does time.time() return?

It returns the current Unix timestamp as a float.

Should I use time or datetime?

Use time for delays and simple timestamps. Use datetime for readable dates and date calculations.

Can time.sleep() use decimal values?

Yes. For example, time.sleep(0.5) pauses for half a second.