Lua Academy · Lesson

os.time and os.date

Get the current time.

os.time and os.date is a free Lua Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

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.

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.

Frequently asked questions

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

Yes — the full text of “os.time and os.date” is free to read here on the web, and the Lua Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Lua Academy course, upgrade to CoddyKit PRO.

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; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

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