Lua OS Library Guide — Time, Date, and System Operations

In this tutorial, you will learn about Lua OS Library Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Lua OS library gives access to operating system functions including time and date manipulation (os.time, os.date, os.difftime), command execution (os.execute), file operations (os.rename, os.remove), and environment variable access (os.getenv).

Time Functions

-- Current time (seconds since epoch)
local now = os.time()
print(now)  --> 1751155200

-- Time from table
local t = os.time({year=2026, month=6, day=28})
print(t)

-- Time difference
local start = os.time()
-- ... do something ...
local elapsed = os.difftime(os.time(), start)
print(elapsed .. " seconds")

Date Formatting

-- Format current time
print(os.date("%Y-%m-%d %H:%M:%S"))  --> 2026-06-28 12:00:00

-- Format specific time
local t = os.time()
print(os.date("%B %d, %Y", t))  --> June 28, 2026

-- Date components
local components = os.date("*t")
print(components.year)   --> 2026
print(components.month)  --> 6
print(components.day)    --> 28
print(components.wday)   --> 1 (Sunday = 1)

System Commands

-- Execute command (returns exit code)
local ok = os.execute("mkdir -p /tmp/test")
if ok then
    print("Directory created")
end

-- Execute and get output
local handle = io.popen("ls -la", "r")
local output = handle:read("*all")
handle:close()
print(output)

File Operations

-- Rename file
local ok, err = os.rename("old.txt", "new.txt")
if not ok then
    print("Rename failed:", err)
end

-- Delete file
os.remove("temp.txt")

-- Get environment variable
local home = os.getenv("HOME")
print("Home directory:", home)

Performance Timing

-- os.clock returns CPU time
local start = os.clock()
for i = 1, 1000000 do
    local x = math.sqrt(i)
end
local elapsed = os.clock() - start
print(string.format("CPU time: %.3f seconds", elapsed))

Common Mistakes

1. os.time without arguments

os.time() returns current time. os.time(table) returns time for a specific date. Forgetting the table parameter defaults to now.

2. Confusing os.clock and os.time

os.clock measures CPU time (program execution). os.time measures wall clock (real-world time).

3. os.execute security risks

os.execute runs shell commands. Never pass untrusted user input to os.execute.

Practice Questions

1. How do you format a date as YYYY-MM-DD? os.date("%Y-%m-%d") or os.date("%Y-%m-%d", timestamp) for a specific time.

2. What does os.time() return? The current time as seconds since the Unix epoch (January 1, 1970 UTC).

3. How do you run a system command in Lua? Use os.execute("command") for the exit code, or io.popen("command", "r") to capture output.

FAQ

{{< faq question="Is os.execute portable?" >}} Partially. The command string is passed to the system shell. On Unix it runs through /bin/sh, on Windows through cmd.exe. {{< /faq >}}

{{< faq question="How accurate is os.clock?" >}} It returns CPU time with typical resolution of milliseconds. For high-precision timing, use the socket library's gettime function. {{< /faq >}}

{{< faq question="Can I set the system time from Lua?" >}} os.time is read-only in most Lua implementations. Setting system time requires os.execute with platform-specific commands. {{< /faq >}}

What's Next

Now learn about debugging techniques in Lua.