PythonBeginner.help

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:

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:

  1. Import the module with import time
  2. Get the current timestamp with time.time()
  3. Pause execution with time.sleep()
  4. 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.

See also #

Press Esc to close