EpochDays

Convert Unix Timestamp in Go

Go's time package provides clean APIs for timestamp conversion. The time.Time type is the core abstraction, with time.Unix() for converting Unix timestamps.

Unix Timestamp to Time

Go
package main

import (
    "fmt"
    "time"
)

func main() {
    // From seconds
    timestamp := int64(1704067200)
    t := time.Unix(timestamp, 0)
    fmt.Println(t.UTC()) // 2024-01-01 00:00:00 +0000 UTC

    // From seconds with nanoseconds
    tNano := time.Unix(1704067200, 500000000)
    fmt.Println(tNano.UTC()) // 2024-01-01 00:00:00.5 +0000 UTC

    // From milliseconds
    timestampMs := int64(1704067200000)
    tMs := time.UnixMilli(timestampMs)
    fmt.Println(tMs.UTC()) // 2024-01-01 00:00:00 +0000 UTC
}

Time to Unix Timestamp

Go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Current timestamp in seconds
    nowSeconds := time.Now().Unix()
    fmt.Println(nowSeconds) // e.g., 1704067200

    // Current timestamp in milliseconds
    nowMs := time.Now().UnixMilli()
    fmt.Println(nowMs) // e.g., 1704067200000

    // Current timestamp in nanoseconds
    nowNano := time.Now().UnixNano()
    fmt.Println(nowNano) // e.g., 1704067200000000000

    // From specific time
    t := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
    timestamp := t.Unix()
    fmt.Println(timestamp) // 1704067200
}

Timezone Handling

Go
package main

import (
    "fmt"
    "time"
)

func main() {
    timestamp := int64(1704067200)
    t := time.Unix(timestamp, 0)

    // UTC
    fmt.Println(t.UTC()) // 2024-01-01 00:00:00 +0000 UTC

    // Load specific timezone
    nyLoc, _ := time.LoadLocation("America/New_York")
    fmt.Println(t.In(nyLoc)) // 2023-12-31 19:00:00 -0500 EST

    tokyoLoc, _ := time.LoadLocation("Asia/Tokyo")
    fmt.Println(t.In(tokyoLoc)) // 2024-01-01 09:00:00 +0900 JST

    // Local timezone
    fmt.Println(t.Local()) // Depends on system timezone

    // Create time in specific timezone
    tInNY := time.Date(2024, 1, 1, 0, 0, 0, 0, nyLoc)
    fmt.Println(tInNY.Unix()) // 1704085200 (different from UTC!)
}

Formatting (The Go Way)

Go uses a unique reference time approach. For common gotchas and a full layout reference, see Go Time Layouts.

Go
timestamp := int64(1704067200)
t := time.Unix(timestamp, 0).UTC()

// Go uses a reference time: Mon Jan 2 15:04:05 MST 2006
fmt.Println(t.Format("2006-01-02"))          // 2024-01-01
fmt.Println(t.Format(time.RFC3339))          // 2024-01-01T00:00:00Z

Common Pitfalls

Forgetting to Handle Errors from LoadLocation

time.LoadLocation() can fail if the timezone database is missing. Always handle the error.

// ❌ Ignoring error
loc, _ := time.LoadLocation("Invalid/Zone")

// ✅ Handle the error
loc, err := time.LoadLocation("America/New_York")
if err != nil {
    log.Fatalf("failed to load timezone: %v", err)
}

Mixing Seconds and Milliseconds

Use the correct function: time.Unix() for seconds, time.UnixMilli() for milliseconds.

// ❌ Wrong - treating milliseconds as seconds
t := time.Unix(1704067200000, 0) // Year 55963!

// ✅ Correct
t := time.UnixMilli(1704067200000) // 2024-01-01

Format String Confusion

Go's format uses reference time Mon Jan 2 15:04:05 MST 2006. Using arbitrary numbers (like "yyyy-mm-dd") won't work.

Edge Cases

Go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Negative timestamps (before 1970)
    before1970 := time.Unix(-86400, 0)
    fmt.Println(before1970.UTC()) // 1969-12-31 00:00:00 +0000 UTC

    // Nanosecond precision
    precise := time.Unix(1704067200, 123456789)
    fmt.Println(precise.Nanosecond()) // 123456789

    // Zero time (useful for "not set")
    var zero time.Time
    fmt.Println(zero.IsZero()) // true
    fmt.Println(zero.Unix())   // -62135596800

    // Maximum representable time
    // Go can represent dates far into the future
    future := time.Date(9999, 12, 31, 23, 59, 59, 0, time.UTC)
    fmt.Println(future.Unix()) // 253402300799
}

Frequently Asked Questions

What package should I use for Unix timestamps in Go?

Use the standard library "time" package. It provides time.Unix() for creating time.Time from timestamps and time.Time.Unix() for converting back.

Does Go use seconds or milliseconds for Unix timestamps?

Go uses seconds for the primary value and nanoseconds for precision. time.Unix(sec, nsec) takes seconds and nanoseconds separately.

How do I handle timezones in Go?

Use time.LoadLocation() to get a *time.Location, then use time.Time.In() to convert. Go stores times in UTC internally with timezone metadata.

What is the time layout format in Go?

Go uses a reference time (Mon Jan 2 15:04:05 MST 2006) as a template. You format dates by showing how this specific reference time would be displayed.