Go Date and Time: A Practical Guide

Working with dates and times is an essential part of application development. Whether you are building REST APIs, managing database records, scheduling background jobs, processing server logs, or converting timestamps, Go provides a powerful standard library for handling date and time operations.

Golang includes the built-in time package, which provides functions and methods for getting the current time, formatting dates, parsing date strings, calculating time differences, handling time zones, and working with Unix timestamps.

In this tutorial, you will learn how to work with dates and times in Go through practical examples.

1. Understanding the Go Time Package

Go provides a standard library package called time for handling date and time operations. You do not need to install any external package to use its basic functionality.

Import the time package along with fmt when you need to display date and time values.

package main

import (
    "fmt"
    "time"
)

func main() {
    currentTime := time.Now()

    fmt.Println("Current Time:", currentTime)
}

The time.Now() function returns the current local date and time.

The output will look similar to:

Current Time: 2026-11-05 21:30:00 +0530 IST

The exact output depends on the system date, time, and timezone.

2. Get the Current Date and Time in Go

You can use time.Now() to retrieve the current date and time. Go also provides methods to extract individual date and time components.

package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()

    fmt.Println("Current Date:", now.Format("2006-01-02"))
    fmt.Println("Current Time:", now.Format("15:04:05"))
    fmt.Println("Year:", now.Year())
    fmt.Println("Month:", now.Month())
    fmt.Println("Day:", now.Day())
    fmt.Println("Hour:", now.Hour())
    fmt.Println("Minute:", now.Minute())
    fmt.Println("Second:", now.Second())
}

This is useful when you need to display dates, generate filenames, create timestamps, or store date and time information in a database.

3. Format Date and Time in Go

Go uses a unique approach to date formatting. Instead of using format characters such as YYYY, MM, and DD, Go uses a predefined reference date:

Mon Jan 2 15:04:05 MST 2006

You create a layout by arranging these reference values in the desired output format.

package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()

    fmt.Println(now.Format("2006-01-02"))
    fmt.Println(now.Format("02-01-2006"))
    fmt.Println(now.Format("2006-01-02 15:04:05"))
    fmt.Println(now.Format("January 02, 2006"))
    fmt.Println(now.Format("03:04 PM"))
    fmt.Println(now.Format(time.RFC3339))
}

Example output:

2026-11-05
05-11-2026
2026-11-05 21:30:00
November 05, 2026
09:30 PM
2026-11-05T21:30:00+05:30

Common Go Date and Time Layouts

Here are some frequently used date and time layouts in Go:

Layout	Output Example
2006-01-02	2026-11-05
02-01-2006	05-11-2026
2006/01/02	2026/11/05
15:04:05	21:30:00
03:04 PM	09:30 PM
2006-01-02 15:04:05	2026-11-05 21:30:00
time.RFC3339	2026-11-05T21:30:00+05:30

Understanding Go’s reference date is important because incorrect layout strings can produce unexpected results.

4. Parse Date Strings in Go

Sometimes an application receives date and time values as strings from users, APIs, configuration files, or databases.

Go provides time.Parse() to convert a formatted date string into a time.Time value.

package main

import (
    "fmt"
    "time"
)

func main() {
    dateString := "2026-11-05 14:30:00"

    layout := "2006-01-02 15:04:05"

    parsedTime, err := time.Parse(layout, dateString)

    if err != nil {
        fmt.Println("Error parsing date:", err)
        return
    }

    fmt.Println("Parsed Date:", parsedTime)
}

The time.Parse() function returns a time value and an error. Always check the error before using the parsed result.

Parse a Date Using a Different Format

You can parse different date formats by providing the appropriate layout.

dateString := "05/11/2026"

parsedTime, err := time.Parse("02/01/2006", dateString)

if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(parsedTime)

Parse Dates Using a Specific Timezone

If a date string does not contain timezone information, time.Parse() interprets it as UTC. Use time.ParseInLocation() when the input represents a local time in a known timezone.

package main

import (
    "fmt"
    "time"
)

func main() {
    location, err := time.LoadLocation("Asia/Kolkata")

    if err != nil {
        fmt.Println(err)
        return
    }

    dateString := "2026-11-05 14:30:00"

    parsedTime, err := time.ParseInLocation(
        "2006-01-02 15:04:05",
        dateString,
        location,
    )

    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println("Local Time:", parsedTime)
    fmt.Println("UTC Time:", parsedTime.UTC())
}

This is particularly useful when processing user-submitted dates or scheduling events across different time zones.

5. Convert Go Date and Time to Unix Timestamp

A Unix timestamp represents the number of seconds elapsed since January 1, 1970, 00:00:00 UTC, also known as the Unix epoch.

Unix timestamps are commonly used in APIs, databases, server logs, authentication systems, and distributed applications.

Go provides the Unix() method to convert a time.Time value into a Unix timestamp.

package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()

    unixSeconds := now.Unix()

    fmt.Println("Current Date:", now)
    fmt.Println("Unix Timestamp:", unixSeconds)
}

Get Unix Timestamp in Milliseconds

If an application requires a timestamp in milliseconds, use UnixMilli().

now := time.Now()

unixMilliseconds := now.UnixMilli()

fmt.Println("Unix Timestamp in Milliseconds:", unixMilliseconds)

Get Unix Timestamp in Microseconds and Nanoseconds

Go also provides methods for microsecond and nanosecond precision.

now := time.Now()

fmt.Println("Seconds:", now.Unix())
fmt.Println("Milliseconds:", now.UnixMilli())
fmt.Println("Microseconds:", now.UnixMicro())
fmt.Println("Nanoseconds:", now.UnixNano())

These methods are useful when integrating Go applications with systems that use different timestamp precision levels.

For a more detailed reference, see the Go Unix Timestamp and Date-Time Conversion Guide, which covers Go timestamp conversion and date-time formatting with practical examples.

6. Convert Unix Timestamp to Date and Time in Go

You can convert a Unix timestamp back into a readable date and time using time.Unix().

package main

import (
    "fmt"
    "time"
)

func main() {
    unixTimestamp := int64(1793908800)

    convertedTime := time.Unix(unixTimestamp, 0)

    fmt.Println("Converted Date:", convertedTime)
    fmt.Println("UTC Date:", convertedTime.UTC())
    fmt.Println("Formatted Date:", convertedTime.Format("2006-01-02 15:04:05"))
}

The time.Unix() function accepts seconds and nanoseconds as arguments.

Convert Millisecond Timestamp to Date

If your application receives a timestamp in milliseconds, use time.UnixMilli().

package main

import (
    "fmt"
    "time"
)

func main() {
    milliseconds := int64(1793908800000)

    convertedTime := time.UnixMilli(milliseconds)

    fmt.Println(convertedTime)
}

Important: Always identify the timestamp unit before conversion. Passing milliseconds to time.Unix() as seconds will produce an incorrect date.

7. Work with UTC and Local Timezones in Go

Timezone conversion is important when developing applications used by people in different countries.

Go supports timezone handling through the time.Location type. You can use UTC() to convert a time value to UTC and In() to display the same instant in another timezone.

package main

import (
    "fmt"
    "time"
)

func main() {
    currentTime := time.Now()

    utcTime := currentTime.UTC()

    location, err := time.LoadLocation("America/New_York")

    if err != nil {
        fmt.Println(err)
        return
    }

    newYorkTime := currentTime.In(location)

    fmt.Println("Local Time:", currentTime)
    fmt.Println("UTC Time:", utcTime)
    fmt.Println("New York Time:", newYorkTime)
}

Convert UTC Time to India Time

package main

import (
    "fmt"
    "time"
)

func main() {
    utcTime := time.Now().UTC()

    indiaLocation, err := time.LoadLocation("Asia/Kolkata")

    if err != nil {
        fmt.Println(err)
        return
    }

    indiaTime := utcTime.In(indiaLocation)

    fmt.Println("UTC:", utcTime)
    fmt.Println("India Time:", indiaTime)
}

Using IANA timezone names such as Asia/Kolkata, Europe/London, and America/New_York is recommended instead of manually adding timezone offsets. This helps applications handle daylight saving time correctly.

8. Calculate Time Difference in Go

Go provides the Sub() method to calculate the duration between two time values.

package main

import (
    "fmt"
    "time"
)

func main() {
    startTime := time.Date(2026, 11, 5, 9, 0, 0, 0, time.UTC)
    endTime := time.Date(2026, 11, 5, 17, 30, 0, 0, time.UTC)

    difference := endTime.Sub(startTime)

    fmt.Println("Hours:", difference.Hours())
    fmt.Println("Minutes:", difference.Minutes())
    fmt.Println("Seconds:", difference.Seconds())
}

Output:

Hours: 8.5
Minutes: 510
Seconds: 30600

This functionality is useful for calculating working hours, processing durations, API response times, and event intervals.

9. Add or Subtract Days, Hours, and Minutes

Go provides Add() and AddDate() to move forward or backward from a given date and time.

Add Hours and Minutes

package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()

    futureTime := now.Add(2 * time.Hour)
    pastTime := now.Add(-30 * time.Minute)

    fmt.Println("Current Time:", now)
    fmt.Println("After 2 Hours:", futureTime)
    fmt.Println("30 Minutes Earlier:", pastTime)
}

Add Days, Months, and Years

Use AddDate() for calendar-based date calculations.

package main

import (
    "fmt"
    "time"
)

func main() {
    today := time.Now()

    tomorrow := today.AddDate(0, 0, 1)
    nextMonth := today.AddDate(0, 1, 0)
    nextYear := today.AddDate(1, 0, 0)

    fmt.Println("Today:", today)
    fmt.Println("Tomorrow:", tomorrow)
    fmt.Println("Next Month:", nextMonth)
    fmt.Println("Next Year:", nextYear)
}

Use AddDate() rather than adding a fixed 24-hour duration when you mean the next calendar day in a particular timezone. Daylight saving transitions can make calendar days shorter or longer than 24 hours.

10. Compare Two Dates in Go

Go provides methods such as Before(), After(), and Equal() to compare time values.

package main

import (
    "fmt"
    "time"
)

func main() {
    date1 := time.Date(2026, 11, 5, 10, 0, 0, 0, time.UTC)
    date2 := time.Date(2026, 11, 6, 10, 0, 0, 0, time.UTC)

    fmt.Println("Date1 Before Date2:", date1.Before(date2))
    fmt.Println("Date1 After Date2:", date1.After(date2))
    fmt.Println("Date1 Equals Date2:", date1.Equal(date2))
}

These methods are useful for checking expiration dates, validating event schedules, and determining whether a deadline has passed.

11. Measure Execution Time in Go

The time package can also measure how long a function or operation takes to execute.

Use time.Now() to record the starting time and time.Since() to calculate the elapsed duration.

package main

import (
    "fmt"
    "time"
)

func main() {
    start := time.Now()

    // Simulate an operation
    time.Sleep(2 * time.Second)

    elapsed := time.Since(start)

    fmt.Println("Execution Time:", elapsed)
}

Output:

Execution Time: 2s

This technique is useful for benchmarking application operations, measuring API processing time, and monitoring application performance.

12. Best Practices for Handling Dates and Times in Go

When working with dates and times in production applications, follow these recommendations:

• Use UTC for storage: Store timestamps in UTC where possible and convert them to local time only when displaying them.
• Use IANA timezone names: Prefer Asia/Kolkata or America/New_York instead of manually calculating timezone offsets.
• Validate parsed dates: Always check errors returned by time.Parse() and time.ParseInLocation().
• Identify timestamp units: Determine whether an incoming timestamp represents seconds, milliseconds, microseconds, or nanoseconds.
• Use RFC3339 for APIs: Prefer standardized formats such as RFC3339 when exchanging date and time values between services.
• Use AddDate for calendar calculations: Avoid assuming that every calendar day contains exactly 24 hours.
• Use Equal for time comparisons: Prefer Time.Equal() over the == operator when comparing time instants.

Conclusion

Go provides a comprehensive standard library for handling date and time operations through its built-in time package. Developers can easily retrieve the current time, format and parse date strings, convert Unix timestamps, work with different time zones, calculate time differences, and measure application execution time.

Understanding these functions helps developers build reliable applications that handle dates and times consistently across different systems and geographical locations.

If you frequently work with Unix timestamps, date formatting, or timezone conversions, explore the Go Date and Time Programming Reference for additional examples and conversion guidance.