time

Go time layouts use the reference timestamp Mon Jan 2 15:04:05 MST 2006, plus Parse, Format, and time-zone conversion.

模块页正文目前为英文。

The time package is the standard-library API for clocks, durations, and locations. Layout strings are not a pattern language such as YYYY-MM-DD. They are a typed-out version of one specific time: Mon Jan 2 15:04:05 MST 2006, also written as 01/02 03:04:05PM '06 -0700.

Examples on this page use fixed input strings and UTC or named locations. They do not call time.Now(), whose value would change on every run.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
time.Parse, time.Time.FormatParse a time from a string, or format a Time, using a layout that refers to the reference timestamp Mon Jan 2 15:04:05 MST 2006.
time.LoadLocation, time.Time.In, time.ParseInLocation, time.FixedZoneConvert an instant into another time zone, or parse a zone-less datetime as if it belongs to a given location.

The reference layout

Each component of the reference time stands for that component in the value you want to parse or format. 2006 is the year, 01 or Jan is the month, 02 is the day, 15 is the hour in 24-hour form, 03 is the hour in 12-hour form, 04 is the minute, 05 is the second, MST or -0700 is the time zone.

A layout of YYYY-MM-DD is therefore not a four-digit year followed by a month and a day. Y, M, and D are not layout tokens, and Parse reports that it cannot match the layout. time.RFC3339 is the predefined layout 2006-01-02T15:04:05Z07:00.

time.Parse, time.Time.Format

func Parse(layout, value string) (Time, error)
func (t Time) Format(layout string) string
const RFC3339 = "2006-01-02T15:04:05Z07:00"

Parse a time from a string, or format a Time, using a layout that refers to the reference timestamp Mon Jan 2 15:04:05 MST 2006.

ParameterDescription
layoutA sample of the reference time, not a numeric pattern such as YYYY-MM-DD. Predefined layouts include time.RFC3339 and time.Kitchen.
valueThe text to parse. It must match the layout, including separators.

Returns: Parse returns the Time and a parse error. When the layout has no time zone, the result is in UTC. Format returns the formatted string and does not return an error.

Errors

  • *time.ParseError — Returned when the value cannot be parsed as the layout. The error text quotes both the layout and the value.
  • Parse("YYYY-MM-DD", "2026-11-21") fails. Parse("2006-01-02", "2026-11-21") succeeds and is reported as UTC.
  • time.Kitchen is "3:04PM". Formatting 15:04 UTC therefore prints 3:04PM.
  • Do not use time.Now() when you need a reproducible example or test.
go
package main

import (
	"fmt"
	"time"
)

func main() {
	wrong, err := time.Parse("YYYY-MM-DD", "2026-11-21")
	fmt.Printf("err=%v zero=%v\n", err, wrong.IsZero())

	ok, err := time.Parse("2006-01-02", "2026-11-21")
	fmt.Printf("%v %v loc=%s\n", ok, err, ok.Location())

	t, err := time.Parse(time.RFC3339, "2026-11-21T15:04:05Z")
	if err != nil {
		panic(err)
	}
	fmt.Println(t.UTC().Format("2006-01-02 15:04:05"))
	fmt.Println(t.Format(time.Kitchen))
}

Expected output

err=parsing time "2026-11-21" as "YYYY-MM-DD": cannot parse "2026-11-21" as "YYYY-MM-DD" zero=true
2026-11-21 00:00:00 +0000 UTC <nil> loc=UTC
2026-11-21 15:04:05
3:04PM

Related: Official Time.Format layouts

Official documentation →

Locations and time zones

A Time stores an instant and a Location. t.In(loc) reports the same instant in another location. LoadLocation looks up an IANA name such as America/New_York and requires zone information on the system; FixedZone builds a location from a name and a fixed offset in seconds, without that database.

ParseInLocation applies a location when the layout has no zone. Parse of a value that already includes an offset does not need it. These examples use 21 November 2026, when America/New_York is Eastern Standard Time (UTC-5).

time.LoadLocation, time.Time.In, time.ParseInLocation, time.FixedZone

func LoadLocation(name string) (*Location, error)
func (t Time) In(loc *Location) Time
func ParseInLocation(layout, value string, loc *Location) (Time, error)
func FixedZone(name string, offset int) *Location

Convert an instant into another time zone, or parse a zone-less datetime as if it belongs to a given location.

ParameterDescription
nameFor LoadLocation, an IANA time-zone name such as America/New_York or UTC. For FixedZone, a label used when formatting, such as UTC-5.
locThe location used by In or ParseInLocation. Passing nil is not equivalent to UTC; use time.UTC.
offsetFor FixedZone, seconds east of UTC. UTC-5 is -5 * 60 * 60.

Returns: LoadLocation returns a *Location or an error if the time-zone database cannot supply that name. In and ParseInLocation return a Time; In uses the same instant as t.

Errors

  • error — LoadLocation fails when the IANA name is unknown or zone information is not available on the system. ParseInLocation returns a parse error when the value does not match the layout.
  • 2026-11-21T15:04:05Z is 10:04:05 EST in America/New_York.
  • Parsing 2026-11-21 15:04:05 in America/New_York produces 20:04:05 UTC, because that local time is five hours behind UTC.
  • FixedZone does not follow daylight-saving rules. Use LoadLocation when the offset can change during the year.
go
package main

import (
	"fmt"
	"time"
)

func main() {
	t, err := time.Parse(time.RFC3339, "2026-11-21T15:04:05Z")
	if err != nil {
		panic(err)
	}
	ny, err := time.LoadLocation("America/New_York")
	if err != nil {
		panic(err)
	}
	inNY := t.In(ny)
	fmt.Println(inNY.Format("2006-01-02 15:04:05 MST"))
	fmt.Println(inNY.Format(time.RFC3339))

	local, err := time.ParseInLocation("2006-01-02 15:04:05", "2026-11-21 15:04:05", ny)
	if err != nil {
		panic(err)
	}
	fmt.Println(local.UTC().Format(time.RFC3339))

	fixed := time.FixedZone("UTC-5", -5*60*60)
	fmt.Println(t.In(fixed).Format("2006-01-02 15:04:05 MST"))

	withOff, err := time.Parse("2006-01-02 15:04:05 -0700", "2026-11-21 15:04:05 -0500")
	if err != nil {
		panic(err)
	}
	fmt.Println(withOff.UTC().Format(time.RFC3339))
}

Expected output

2026-11-21 10:04:05 EST
2026-11-21T10:04:05-05:00
2026-11-21T20:04:05Z
2026-11-21 10:04:05 UTC-5
2026-11-21T20:04:05Z

Related: time.LoadLocation

Official documentation →