Golang Time: Now, Sleep, Format, Parse and Durations

The basics in one program

package main

import (
	"fmt"
	"time"
)

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

	time.Sleep(50 * time.Millisecond)

	elapsed := time.Since(start)
	fmt.Println("slept at least 50ms:", elapsed >= 50*time.Millisecond)

	t := time.Date(2026, time.September, 23, 14, 30, 0, 0, time.UTC)
	fmt.Println(t)
	fmt.Println(t.Format("2006-01-02 15:04"))
	fmt.Println(t.Format("Monday, January 2, 2006"))
	fmt.Println("in 90 minutes:", t.Add(90*time.Minute).Format(time.Kitchen))
}

time.Now() returns the current local time, time.Sleep pauses the current goroutine, time.Since measures elapsed time, and time.Date builds a specific moment. The rest of this page takes each piece in turn. The examples use fixed dates and UTC so their output is the same wherever you run them.

Sleep and Duration

A time.Duration is an int64 count of nanoseconds. The package defines constants to build readable values:

There is no time.Day, because a day is not always 24 hours when a time zone changes for daylight saving. Use AddDate for calendar days (see below).

package main

import (
	"fmt"
	"time"
)

func main() {
	d := 90 * time.Minute
	fmt.Println(d)                      // 1h30m0s
	fmt.Println(d.Hours(), d.Minutes()) // float64 values
	fmt.Println(2*time.Hour + 15*time.Second)

	// Multiplying by a variable needs a conversion: int * Duration does not compile.
	retries := 3
	backoff := time.Duration(retries) * 200 * time.Millisecond
	fmt.Println("backoff:", backoff)

	// Parse a duration from a string (for flags and config files).
	timeout, err := time.ParseDuration("1m30s")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("timeout:", timeout, "=", timeout.Seconds(), "seconds")

	// Round and truncate a measured duration for display.
	measured := 1234567891 * time.Nanosecond
	fmt.Println(measured, measured.Round(time.Millisecond), measured.Truncate(time.Second))
}

Two common bugs come from Duration being an integer:

• time.Sleep(5) sleeps 5 nanoseconds. Always multiply by a unit: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) does not compile when n is an int variable. Convert it: time.Duration(n) * time.Second. A constant like 5 works without conversion because untyped constants adapt to the Duration type.

ParseDuration accepts ns, us (or µs), ms, s, m and h, combined like "2h45m" or "1.5s". It has no unit for days.

Formatting: the 2006-01-02 reference layout

Go does not use %Y-%m-%d or yyyy-MM-dd. A layout is the reference time

Mon Jan 2 15:04:05 MST 2006

written the way you want your output to look. The values are chosen so each one is unique: month 1, day 2, hour 3 (or 15), minute 4, second 5, year 6 (2006), zone offset -7 (-0700). Read it as 01/02 03:04:05PM '06 -0700.

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.March, 5, 9, 7, 3, 250_000_000, time.UTC)

	layouts := []string{
		"2006-01-02",
		"02/01/2006",
		"01/02/06",
		"Jan 2, 2006",
		"Monday 2 January 2006",
		"15:04:05",
		"3:04 PM",
		"2006-01-02T15:04:05.000Z07:00",
		time.RFC3339,
		time.DateTime,
		time.RFC1123,
	}
	for _, l := range layouts {
		fmt.Printf("%-32q %s\n", l, t.Format(l))
	}
}

The layout tokens you will need most:

Predefined layouts:

The classic mistake is writing a layout with the wrong numbers, for example "2023-01-01". Go does not reject it. It copies characters it does not recognize and substitutes the ones it does: each 2 is the day, 3 is the 12-hour clock hour and both 01s are the month, so March 5 at 9:07 formats as 5059-03-03. A layout like "YYYY-MM-DD" contains no tokens at all and prints itself unchanged. If formatted dates look strange, check that the layout uses exactly the reference values.

Parsing strings into times

time.Parse(layout, value) uses the same layouts, and returns an error you must check:

package main

import (
	"fmt"
	"time"
)

func main() {
	t, err := time.Parse("2006-01-02 15:04", "2026-09-23 18:45")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t, "| location:", t.Location())

	// A string with an offset keeps that offset.
	t2, err := time.Parse(time.RFC3339, "2026-09-23T18:45:00+02:00")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t2, "| in UTC:", t2.UTC())

	// Interpret a zone-less string in a specific zone.
	tokyo := time.FixedZone("JST", 9*60*60)
	t3, err := time.ParseInLocation(time.DateTime, "2026-09-23 18:45:00", tokyo)
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t3, "| in UTC:", t3.UTC())

	// A wrong input produces a descriptive error.
	_, err = time.Parse(time.DateOnly, "23/09/2026")
	fmt.Println("error:", err)
}

Without a zone in the input, Parse returns UTC. The same wall-clock string can mean different instants depending on the zone, which is why ParseInLocation exists. The error message names the part that failed to match, which helps when you are debugging a layout.

Time zones

A time.Time is an instant plus a location used for display. Changing the location with In changes how it prints, not which moment it is.

package main

import (
	"fmt"
	"time"
	_ "time/tzdata" // embed the zone database so LoadLocation works anywhere
)

func main() {
	meeting := time.Date(2026, time.September, 23, 15, 0, 0, 0, time.UTC)

	ny, err := time.LoadLocation("America/New_York")
	if err != nil {
		fmt.Println("load location:", err)
		return
	}
	india := time.FixedZone("IST", 5*60*60+30*60) // +05:30, no DST rules

	fmt.Println("UTC:     ", meeting.Format(time.RFC1123))
	fmt.Println("New York:", meeting.In(ny).Format(time.RFC1123))
	fmt.Println("India:   ", meeting.In(india).Format(time.RFC1123))
	fmt.Println("same instant:", meeting.Equal(meeting.In(ny)))
}

• time.UTC is always available. Store and transmit times in UTC (or RFC 3339 with an offset) and convert only for display.
• time.Local is the machine's zone. On servers and in containers it is often UTC, and on a laptop it is not, so code that depends on it behaves differently in each place.
• time.LoadLocation("Europe/Berlin") reads the IANA database from the operating system. Minimal container images often lack it, and the call then returns an error. The blank import _ "time/tzdata" embeds the database in your binary (about 450 KB) so it always works. Always handle the error.
• time.FixedZone(name, offsetSeconds) creates a zone with a constant offset. It has no daylight saving rules, so use it for offsets you received, not for named regions.

Arithmetic and comparison

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Date(2026, time.January, 31, 10, 0, 0, 0, time.UTC)
	end := time.Date(2026, time.March, 1, 12, 30, 0, 0, time.UTC)

	fmt.Println("difference:", end.Sub(start))
	fmt.Println("in days:   ", int(end.Sub(start).Hours()/24))

	fmt.Println("+36h:      ", start.Add(36*time.Hour).Format(time.DateTime))
	fmt.Println("-1 week:   ", start.AddDate(0, 0, -7).Format(time.DateOnly))
	fmt.Println("+1 month:  ", start.AddDate(0, 1, 0).Format(time.DateOnly)) // Jan 31 + 1 month

	fmt.Println("before:", start.Before(end), "after:", start.After(end), "equal:", start.Equal(end))

	// Start of the day, and parts of a date.
	y, m, d := end.Date()
	midnight := time.Date(y, m, d, 0, 0, 0, 0, end.Location())
	fmt.Println("midnight:", midnight.Format(time.DateTime))
	fmt.Println("weekday:", end.Weekday(), "day of year:", end.YearDay())

	// Unix timestamps.
	fmt.Println("unix:", start.Unix(), "ms:", start.UnixMilli())
	fmt.Println("from unix:", time.Unix(1_790_000_000, 0).UTC())
}

Things to notice in the output:

• AddDate(0, 1, 0) on January 31 gives March 3, not February 28. Go adds one month to get "February 31" and then normalizes the overflow. If you need "same day next month, clamped", write that logic yourself.
• Sub returns a Duration, which tops out at about 292 years. For differences in calendar days, compare dates at midnight UTC and divide by 24 hours.
• To get the start of the day, rebuild the time from Date(). t.Truncate(24 * time.Hour) rounds relative to the zero time in UTC, so it gives the wrong answer for any zone other than UTC.

Compare with Equal, Before, After, never with ==. time.Now() includes a monotonic clock reading, used so that time.Since stays correct if the wall clock is adjusted. == compares that reading and the location too, so two Time values for the same instant can be unequal. For the same reason, do not use time.Time as a map key without normalizing it first (t.UTC().Round(0) strips the monotonic reading).

The zero time.Time is January 1, year 1, 00:00 UTC. Check for it with t.IsZero().

Measuring elapsed time

start := time.Now()
doWork()
log.Printf("doWork took %v", time.Since(start))

time.Since(start) is time.Now().Sub(start), and time.Until(deadline) is deadline.Sub(time.Now()). Both use the monotonic clock when available, so they are safe against system clock changes. For benchmarking code, use Go's benchmark support in the testing package instead of timing by hand.

Timers and tickers

time.After(d) returns a channel that receives once after d. A time.Timer is the same thing with a Stop method. A time.Ticker delivers a value every period until you stop it.

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(20 * time.Millisecond)
	defer ticker.Stop()

	done := time.NewTimer(110 * time.Millisecond)
	defer done.Stop()

	ticks := 0
	for {
		select {
		case <-ticker.C:
			ticks++
			fmt.Println("tick", ticks)
			if ticks == 3 {
				fmt.Println("got three ticks, stopping early")
				return
			}
		case <-done.C:
			fmt.Println("timer fired first")
			return
		}
	}
}

The three ticks at 20, 40 and 60 ms arrive well before the 110 ms timer, so the program stops after the third tick. time.AfterFunc(d, f) runs f in its own goroutine after d, which is handy for one-off delayed work.

Since Go 1.23, timers and tickers that are no longer referenced are garbage collected even if you never call Stop, and a stopped or reset timer's channel no longer delivers a stale value. Calling Stop with defer is still the clear way to say the ticker's life is over. When a time limit applies to a whole operation rather than one wait, a context.WithTimeout usually reads better than a timer.

Time in JSON

time.Time marshals to and from RFC 3339 strings in JSON automatically, with nanosecond precision:

type Event struct {
	Name string    `json:"name"`
	At   time.Time `json:"at"`
}
// {"name":"deploy","at":"2026-09-23T14:30:00Z"}

A JSON string in a different format fails to unmarshal. For Unix timestamps or custom formats, store an int64 or a string and convert, or define a type with its own UnmarshalJSON.

Common mistakes

• time.Sleep(1) or time.Sleep(n) with a bare number. That is nanoseconds.
• Layouts with the wrong digits. "2023-01-01" or "YYYY-MM-DD" are not layouts. Use "2006-01-02".
• Mixing up minutes and months. Minutes are 04, months are 01. "15:01" prints the hour and then the month, not the minute.
• Comparing with ==. Use Equal.
• Relying on time.Local. It differs between machines. Be explicit with time.UTC or a loaded location.
• Ignoring the error from LoadLocation or Parse. Both fail on real input. A failed Parse returns the zero time, which prints as year 1, and a failed LoadLocation returns a nil location that makes t.In(loc) panic.