Lua Academy · Lesson

os.time and os.date

Get the current time.

Lesson 1 of 413 steps

os.time and os.date is a free Lua Academy lesson on CoddyKit. This is lesson 1 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, and your progress syncs across the web and the CoddyKit app. The Lua Academy course includes 4 lessons in total.

Why Time Matters

Programs often need to know the current time. A game records when you scored, a log file stamps each event, and a reminder app counts down to a deadline.

Lua keeps its time tools in the built-in os library. The two stars are os.time and os.date. In this lesson you will meet both.

os.time Returns a Number

os.time() with no arguments returns the current moment as a single number.

That number is the count of seconds since a fixed point in the past (the epoch). It is just an integer, so you can store it, compare it, or do math with it.

local now = os.time()
print(now)
print(type(now))

The Epoch

On most systems the epoch is midnight on January 1, 1970, UTC. So os.time() tells you how many seconds have passed since then.

A big number like 1700000000 is normal. It grows by one every second, which makes it perfect for comparing two moments.

local seconds = os.time()
print("Seconds since 1970:", seconds)

os.date Returns Text

A raw second count is hard to read. os.date() turns time into human-friendly text.

Called with no arguments, it returns a readable string describing the current date and time, using your system's local settings.

print(os.date())

os.date With a Format

You usually pass os.date a format string. Special codes starting with % are replaced with parts of the date.

%Y is the 4-digit year, %m the month, and %d the day. Other text stays as-is.

print(os.date("Year: %Y"))
print(os.date("%Y-%m-%d"))

Combining time and date

os.date can take a second argument: a time number. Pass it the result of os.time and it formats that exact moment.

Without the second argument it uses the current time, so these two calls describe the same instant.

local t = os.time()
print(os.date("%Y-%m-%d", t))

Local vs UTC

By default os.date uses your local timezone. To get UTC (universal time) instead, start the format string with an exclamation mark !.

This matters for servers and apps used across the world, where everyone should agree on a single clock.

print("Local:", os.date("%H:%M"))
print("UTC:  ", os.date("!%H:%M"))

The Table Form

If you pass "*t" as the format, os.date returns a table instead of a string.

The table has named fields like year, month, day, hour, min, and sec. This is handy when you need one piece on its own.

local d = os.date("*t")
print(d.year, d.month, d.day)
print(d.hour, d.min, d.sec)

Reading One Field

Because the table form gives named fields, grabbing just the current month or just the current hour is easy.

Use !*t for the UTC version of the table. Each field is a plain number you can use in conditions.

local d = os.date("*t")
if d.hour < 12 then
  print("Good morning")
else
  print("Good afternoon")
end

os.time From a Table

os.time also works in reverse. Give it a table with year, month, and day and it returns the second count for that date.

This lets you build a time value for any specific calendar date you choose.

local t = os.time({year=2020, month=1, day=1, hour=0})
print(t)
print(os.date("%Y-%m-%d", t))

Round Trip

You can move freely between the two forms: os.time turns a table into a number, and os.date("*t", n) turns a number back into a table.

This round trip is the foundation for date math, which you will explore in later lessons.

local n = os.time({year=2021, month=6, day=15})
local back = os.date("*t", n)
print(back.year, back.month, back.day)

Quick Check

Test your understanding of the two main functions.

Answer it in the interactive lesson

Recap

os.time() gives the current moment as a number of seconds since the epoch. os.date() turns time into text using % format codes, or into a table with "*t".

Add ! for UTC, and pass a time number as the second argument to format a specific instant. Together they cover almost every date need in Lua.

Free to start

Learn Lua with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 40
Lessons: 159

Start learning free View the full course

Frequently Asked Questions

Is the “os.time and os.date” lesson free?

Yes — any 3 lessons of the Lua Academy learning path, including “os.time and os.date”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Lua Academy course includes 4 lessons in total.

What will I learn in “os.time and os.date”?

Get the current time. You practise Lua Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Lua Academy?

No prior experience is required. Lua Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 1 of 4.

How long does the “os.time and os.date” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Lua Academy lesson?

Yes. Every Lua Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Lua Academy