Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Time, Math and Randomness

Go time.Format() and time.Parse() functions

Reference for Go time.Format, time.Parse and ParseInLocation: the reference-time layout, ready-made constants, parse errors and time zone pitfalls.

Go does not use %Y-%m-%d style codes to format dates. Instead, a layout is an example of how one specific moment, the reference time, would look in the format you want. Time.Format renders a time using such a layout, and time.Parse reads a string that follows one.

The reference time is Mon Jan 2 15:04:05 MST 2006, which is the same as 01/02 03:04:05PM '06 -0700. Each part has a fixed value (month 1, day 2, hour 3 or 15, minute 4, second 5, year 2006, zone offset -7 hours), and that is how Go recognizes which part you mean.

Go
t := time.Date(2026, time.March, 9, 14, 5, 7, 0, time.UTC)
fmt.Println(t.Format("2006-01-02 15:04")) // 2026-03-09 14:05

Try it

Go Formatting with layouts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Parsing and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func (t Time) Format(layout string) string
func (t Time) AppendFormat(b []byte, layout string) []byte
func Parse(layout, value string) (Time, error)
func ParseInLocation(layout, value string, loc *Location) (Time, error)
Name Description
layout The reference time written the way you want times to look.
value The text to parse. It must match the layout exactly, including separators.
loc Location used for text that has no zone information.

Returns: Format returns the text. Parse returns the time, or the zero Time and an error.

Layout elements:

Meaning Layout text
Year 2006 or 06
Month 01, 1, Jan, January
Day 02, 2, _2 (space padded)
Weekday Mon, Monday
Hour 15 (24-hour), 03 or 3 (12-hour) with PM or pm
Minute, second 04, 4, 05, 5
Fraction .000 fixed digits, .999 trailing zeros removed
Zone MST (name), -0700, -07:00, Z07:00 (prints Z for UTC)

Errors: a *time.ParseError describes the mismatch, the out-of-range value, or the trailing text that was not consumed.

Usage notes

  • Remember the numbers 1 2 3 4 5 6 7: month, day, hour (12-hour), minute, second, year, zone. A layout like 2006-02-01 swaps day and month without any warning, because both are valid parts.
  • Use the constants (time.RFC3339, time.DateOnly, time.DateTime, time.TimeOnly, time.Kitchen, and so on) for standard formats. DateOnly, TimeOnly and DateTime were added in Go 1.20.
  • A fractional second after the seconds field is accepted when parsing even if the layout has none, but not the other way around: a layout with .000 needs exactly that many digits in the text.
  • Parse without a zone gives UTC. If your text means local wall-clock time, call ParseInLocation with time.Local or a location from time.LoadLocation. LoadLocation needs a time zone database on the machine (or the time/tzdata package imported).
  • Zone abbreviations are unreliable. Parsing EST cannot know which EST you mean; if the abbreviation is not the local zone's, Go fabricates a location with that name and a zero offset. Prefer numeric offsets.
  • Output of a month or weekday name is English only. Go has no built-in localization; use golang.org/x/text for other languages.
  • Time values compare with Equal, Before and After, not ==, because == also compares the location pointer and the monotonic reading.
  • JSON encodes a Time as RFC 3339 by default; see json.Marshal().