Time formatting, parsing and zones
Go does not use yyyy-MM-dd in a format string. A layout is a real instant, the reference time Mon Jan 2 15:04:05 MST 2006, and a program writes the pattern it wants by writing that instant in that shape. Parsing uses the same layout, so the two directions cannot disagree.
The reference layout
Every number in the layout is a component of the reference instant: 2006 is the year, 01 the month, 02 the day, 15 the hour on a 24-hour clock, 04 the minute and 05 the second. Jan, Mon and MST are the names, and time.RFC3339 is a constant with the layout the protocol uses.
package main
import (
"fmt"
"time"
)
func main() {
t := time.Date(2026, 11, 18, 14, 5, 9, 0, time.UTC)
fmt.Println(t.Format("2006-01-02 15:04:05"))
fmt.Println(t.Format(time.RFC3339))
fmt.Println(t.Format("Mon 02 Jan 2006"))
fmt.Println(t.Format("15:04"))
}
go build -o app main.go && ./app
2026-11-18 14:05:09
2026-11-18T14:05:09Z
Wed 18 Nov 2026
14:05
The same instant printed four ways, and the weekday came from the calendar rather than from the layout. A layout with 03 instead of 15 prints a 12-hour clock, and PM prints the marker; the reference values are the only magic, everything else is literal text.
Parse
time.Parse reads a string with the same kind of layout. Without a zone in the layout the result is in UTC, which is why the printed instant ends in +0000 UTC. The components are then available as methods, and Month and Weekday are named types whose String method prints the English name.
package main
import (
"fmt"
"time"
)
func main() {
t, err := time.Parse("2006-01-02 15:04", "2026-11-18 14:05")
fmt.Println(t.UTC())
fmt.Println("error:", err)
fmt.Println("year:", t.Year(), "month:", t.Month(), "day:", t.Day())
fmt.Println("weekday:", t.Weekday())
}
go build -o app main.go && ./app
2026-11-18 14:05:00 +0000 UTC
error: <nil>
year: 2026 month: November day: 18
weekday: Wednesday
A layout that matches gives an error of nil and a time with the second at zero, because the layout had no seconds. A layout with a zone such as Z07:00 reads the offset from the string, and time.ParseInLocation reads a zone-less string in a location the program names.
A parse error
A string that does not match the layout returns the zero time and an error that names the layout, the input and the first part that could not be read. The zero time is 0001-01-01 in UTC, and a program that ignores the error formats that date into a report, which is how a missing value becomes a very old one.
package main
import (
"fmt"
"time"
)
func main() {
t, err := time.Parse("2006-01-02", "18/11/2026")
fmt.Println("time:", t)
fmt.Println("error:", err)
}
go build -o app main.go && ./app
time: 0001-01-01 00:00:00 +0000 UTC
error: parsing time "18/11/2026" as "2006-01-02": cannot parse "18/11/2026" as "2006"
The input was day-first and the layout year-first, so the parser stopped at the first character. The error is worth reading once: it names the two strings in full, which is enough to see that one of them is wrong. A program that accepts several layouts tries them in order and keeps the last error.
Zones and offsets
A location is a set of rules, not a number, and an offset is what those rules give for one instant. The fixed zone below is three hours ahead all year, so the same instant prints at five past five with a +03:00 offset. A real zone such as Europe/Berlin changes its offset twice a year and needs the zone database, which a container image may or may not carry.
package main
import (
"fmt"
"time"
)
func main() {
loc := time.FixedZone("UTC+3", 3*3600)
t := time.Date(2026, 11, 18, 14, 5, 0, 0, time.UTC)
fmt.Println("utc:", t.Format(time.RFC3339))
fmt.Println("plus3:", t.In(loc).Format(time.RFC3339))
_, offset := t.In(loc).Zone()
fmt.Println("offset:", offset)
}
go build -o app main.go && ./app
utc: 2026-11-18T14:05:00Z
plus3: 2026-11-18T17:05:00+03:00
offset: 10800
In changes the presentation and not the instant: both lines name the same moment, which is the difference between a timestamp and a wall-clock reading. The offset is in seconds, so three hours is 10800, and a negative offset is a negative number.
Unix time
Unix returns seconds since 1970 in UTC and UnixNano nanoseconds, and time.Unix builds the instant back. The round trip loses nothing at second precision and only what the nanoseconds hold at the other. The last line converts ninety seconds into a duration, which prints as 1m30s.
package main
import (
"fmt"
"time"
)
func main() {
t := time.Date(2026, 11, 18, 14, 5, 0, 0, time.UTC)
fmt.Println("unix:", t.Unix())
fmt.Println("unixnano:", t.UnixNano())
fmt.Println("from:", time.Unix(t.Unix(), 0).UTC().Format(time.RFC3339))
fmt.Println("duration:", time.Duration(90)*time.Second)
}
go build -o app main.go && ./app
unix: 1795010700
unixnano: 1795010700000000000
from: 2026-11-18T14:05:00Z
duration: 1m30s
A Unix timestamp is the right thing to store in a database and the wrong thing to show a user. A duration and a timestamp are different types on purpose: adding a duration to a time gives a time, subtracting two times gives a duration, and the compiler refuses the other combinations.
UTC in, local out
The convention that survives users in several zones: parse and store in UTC, convert to a location only when formatting for a person. A layout without a zone parses as UTC, so a naive parse is already on the right side; a string from a browser arrives with an offset and RFC3339 reads it. A program that compares times from two sources must bring them to one location first, and Equal does that for it.
The zone database is the one deployment detail: time.LoadLocation("Europe/Berlin") reads it, and a minimal image may not have it. A program that formats local time for users either embeds the database or keeps the offsets it needs; the next lessons do not depend on it.
Exercises
- Print the same instant with 03:04 PM and with 15:04. Which reference numbers changed, and what does PM add?
- Parse "2026-11-18T14:05:00+03:00" with time.RFC3339 and print it in UTC. What happens to the clock reading, and what happens to the instant?
- Format a parsed time with a layout that includes MST. What does it print for a time parsed without a zone, and why?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is the reference time in Go?
Answer
Mon Jan 2 15:04:05 MST 2006
Every layout number comes from that instant.
-
Which layout prints a 24-hour clock?
Answer
15:04
15 is the reference hour on a 24-hour clock.
-
What zone does time.Parse use when the layout has none?
Answer
UTC
ParseInLocation is the variant that takes a zone.
-
What is the zero time?
Answer
0001-01-01 00:00:00 UTC
It is what a failed Parse returns.
-
What does a parse error name?
Answer
The layout, the input and the first part that failed
That is enough to see which side is wrong.
-
What does t.In(loc) change?
Answer
The presentation, not the instant
The same moment in another zone.
-
What unit does Zone return for the offset?
Answer
Seconds
+03:00 is 10800 seconds.
-
What does Unix return?
Answer
Seconds since 1970 in UTC
UnixNano is the nanosecond form.
-
What does subtracting two times give?
Answer
A Duration
Time plus Duration and Time minus Time are the two operations.
-
Which convention keeps timestamps honest?
Answer
Store UTC, format in a local zone for display
The instant stays one value, the rendering varies.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev