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.
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
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.
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
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-01swaps 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,TimeOnlyandDateTimewere 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
.000needs exactly that many digits in the text. Parsewithout a zone gives UTC. If your text means local wall-clock time, callParseInLocationwithtime.Localor a location fromtime.LoadLocation.LoadLocationneeds a time zone database on the machine (or thetime/tzdatapackage imported).- Zone abbreviations are unreliable. Parsing
ESTcannot know whichESTyou 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/textfor other languages. - Time values compare with
Equal,BeforeandAfter, not==, because==also compares the location pointer and the monotonic reading. - JSON encodes a
Timeas RFC 3339 by default; seejson.Marshal().
Related
time,time.Now(),time.Duration,time.Since()- Lessons: Time, fmt in depth