Convert a Unix Timestamp to Ruby DateTime

By the end of this page, you will understand how Unix timestamps work in Ruby, how to convert them into Time and DateTime objects, when to use each type, and what common mistakes to avoid when dealing with time zones and epoch values.

A Unix timestamp is the number of seconds that have passed since January 1, 1970 00:00:00 UTC. It is a very common way to store or transmit dates in databases, APIs, log files, and background jobs.

In Ruby, the most common way to convert a Unix timestamp is to first create a Time object:

time = Time.at(1700000000)

If you specifically need a DateTime, you can convert that Time object:

require 'date'

datetime = Time.at(1700000000).to_datetime

This matters because Ruby has multiple date/time types:

• Time for most general timestamp work
• Date for calendar dates without a time-of-day
• DateTime for date-time values when you specifically need that class

In real Ruby programs, developers usually prefer Time unless they have a reason to use DateTime. But if your code, library, or data model expects DateTime, converting from a Unix timestamp is straightforward using Time.at(...).to_datetime.

Think of a Unix timestamp as a counter that starts at zero on January 1, 1970 UTC.

• 0 means the starting point
• 60 means 60 seconds later
• 3600 means one hour later
• 1700000000 means a very large number of seconds later

Ruby's Time.at is like saying: "Show me the calendar date and clock time at this many seconds after the starting point."

If you then call to_datetime, you are changing the object into a different date/time representation, while keeping the same moment in time.

The core syntax is:

Time.at(unix_timestamp)

If you need a DateTime object:

require 'date'

Time.at(unix_timestamp).to_datetime

Example 1: Convert to Time

timestamp = 1700000000
result = Time.at(timestamp)

puts result

This creates a Ruby Time object from the Unix timestamp.

Example 2: Convert to DateTime

require 'date'

timestamp = 1700000000
result = Time.at(timestamp).to_datetime

puts result

This creates a DateTime object.

Example 3: UTC conversion

Unix timestamps are based on UTC, so you often want to be explicit:

 

timestamp = 
result = .at(timestamp).utc.to_datetime

puts result

Consider this example:

require 'date'

timestamp = 1700000000

time = Time.at(timestamp)
datetime = time.to_datetime

puts time
puts datetime

Step by step:

1. require 'date'

   • Loads Ruby's date library so DateTime is available.

2. timestamp = 1700000000

   • Stores the Unix timestamp in a variable.
   • This number means "1700000000 seconds after January 1, 1970 UTC".

3. time = Time.at(timestamp)

   • Ruby converts the integer into a Time object.
   • You now have a full date and time representation.

4. datetime = time.to_datetime

   • Ruby converts the Time object into a DateTime object.
   • The represented moment stays the same.

5. puts time

Unix timestamp conversion appears in many real programs:

• API responses

  • An external API may return created_at: 1700000000.
  • Your Ruby app converts it before displaying it.

• Database records

  • Some systems store timestamps as integers for portability.
  • Ruby converts them when reading data.

• Log processing

  • Server logs often contain epoch-based times.
  • Scripts convert them into human-readable dates.

• Background jobs

  • A scheduled task may run at a timestamp stored in Redis or a queue.
  • Ruby converts the integer into a time object to compare or schedule work.

• Data imports

  • CSV or JSON files may contain Unix timestamps.
  • Ruby converts them during parsing and validation.

In real Ruby codebases, developers usually use a few common patterns around timestamp conversion.

1. Parse incoming data safely

def parse_created_at(data)
  return nil unless data[:created_at]

  Time.at(data[:created_at]).utc
end

This uses a guard clause to avoid errors when the timestamp is missing.

2. Convert only when needed

def created_at_datetime(timestamp)
  Time.at(timestamp).utc.to_datetime
end

If another part of the app specifically needs DateTime, convert at that boundary.

3. Validate timestamp values

def valid_timestamp?(value)
  value.is_a?(Integer) && value >= 0
end

This helps avoid passing strings or invalid data into Time.at.

4. Be explicit about time zone

Here are common beginner mistakes when converting Unix timestamps in Ruby.

1. Forgetting that Time.at already returns a Time

Broken expectation:

result = Time.at(1700000000)
# expecting DateTime directly

Time.at returns a Time, not a DateTime.

Use this if you need DateTime:

require 'date'
result = Time.at(1700000000).to_datetime

2. Forgetting to require date

Broken code:

result = Time.at(1700000000).to_datetime

In some environments, DateTime support may not be loaded yet.

Safer version:

# Unix timestamp -> Time
Time.at(timestamp)

# Unix timestamp -> UTC Time
Time.at(timestamp).utc

# Unix timestamp -> DateTime
require 'date'
Time.at(timestamp).to_datetime

# Unix timestamp -> UTC DateTime
require 'date'
Time.at(timestamp).utc.to_datetime

Rules to remember

• Unix timestamps are usually in seconds since 1970-01-01 00:00:00 UTC
• Time.at(...) returns a Time object
• Use .to_datetime if you specifically need DateTime
• Be careful with milliseconds vs seconds
• Use .utc when you want predictable timezone handling

Common input cleanup

timestamp = params[:timestamp].to_i
Time.at(timestamp).utc

Epoch example

.at()

How do I convert a Unix timestamp to a Ruby DateTime?

Use:

require 'date'
Time.at(timestamp).to_datetime

How do I convert a Unix timestamp to Ruby Time?

Use:

Time.at(timestamp)

Should I use Time or DateTime in Ruby?

For most Ruby programs, use Time. Use DateTime only when you specifically need that class.

Why does my converted time look different on another machine?

Because local time zones may differ. Use .utc to make the result consistent.

What if my timestamp is in milliseconds?

Divide by 1000 before passing it to Time.at.

Time.at(milliseconds / 1000)

• Time — The main Ruby class for representing a specific moment in time.
• DateTime — Related because it is the target type in this conversion.
• Date — Useful when you only need a calendar date without a time.
• Time zones — Important because timestamp display can change between local time and UTC.
• Type conversion — Relevant because you convert an integer into a Ruby date/time object.
• Integer parsing — Useful when timestamps arrive as strings from forms, JSON, or APIs.
• Data validation — Important for checking whether a timestamp is present and valid before conversion.