time package - time - Go Packages Skip to Main Content Why Go Case Studies Common problems companies solve with Go Use Cases Stories about how and why companies use Go Security How Go can help keep you secure by default Learn Docs Effective Go Tips for writing clear, performant, and idiomatic Go code Go User Manual A complete introduction to building software with Go Standard library Reference documentation for Go's standard library Release Notes Learn what's new in each Go release API Reference documentation for the pkg.go.dev API Packages Community Recorded Talks Videos from prior events Meetups Meet other local Go developers Conferences Learn and network with Go developers from around the world Go blog The Go project's official blog. Go project Get help and stay informed from Go Get connected Why Go Why Go Case Studies Use Cases Security Learn Docs Docs Effective Go Go User Manual Standard library Release Notes API Packages Community Community Recorded Talks Meetups Conferences Go blog Go project Get connected Discover Packages Standard library time time package standard library Version: go1.26.6 Opens a new window with list of versions in this module. Latest Latest This package is not in the latest version of its module. Go to latest Published: Aug 13, 2026 License: BSD-3-Clause Opens a new window with license information. Imports: 9 Opens a new window with list of imports. Imported by: 2,818,893 Opens a new window with list of known importers. Main Versions Licenses Imports Imported By Details Valid go.mod file The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go. Redistributable license Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed. Tagged version Modules with tagged versions give importers more predictable builds. Stable version When a project reaches major version v1 it is considered stable. Learn more about best practices Repository cs.opensource.google/go/go Links Report a Vulnerability Jump to ... Documentation Overview Index Examples After Date Duration Duration.Abs Duration.Hours Duration.Microseconds Duration.Milliseconds Duration.Minutes Duration.Nanoseconds Duration.Round Duration.Seconds Duration.String Duration.Truncate FixedZone LoadLocation Location Month NewTicker Parse ParseDuration ParseInLocation Since Sleep Tick Time.Add Time.AddDate Time.After Time.AppendBinary Time.AppendFormat Time.AppendText Time.Before Time.Date Time.Day Time.Equal Time.Format Time.Format (Pad) Time.GoString Time.Round Time.String Time.Sub Time.Truncate Time.Unix Unix UnixMicro UnixMilli Until Constants Variables Functions After(d) Sleep(d) Tick(d) Types type Duration ParseDuration(s) Since(t) Until(t) (d) Abs() (d) Hours() (d) Microseconds() (d) Milliseconds() (d) Minutes() (d) Nanoseconds() (d) Round(m) (d) Seconds() (d) String() (d) Truncate(m) type Location FixedZone(name, offset) LoadLocation(name) LoadLocationFromTZData(name, data) (l) String() type Month (m) String() type ParseError (e) Error() type Ticker NewTicker(d) (t) Reset(d) (t) Stop() type Time Date(year, month, day, hour, min, sec, nsec, loc) Now() Parse(layout, value) ParseInLocation(layout, value, loc) Unix(sec, nsec) UnixMicro(usec) UnixMilli(msec) (t) Add(d) (t) AddDate(years, months, days) (t) After(u) (t) AppendBinary(b) (t) AppendFormat(b, layout) (t) AppendText(b) (t) Before(u) (t) Clock() (t) Compare(u) (t) Date() (t) Day() (t) Equal(u) (t) Format(layout) (t) GoString() (t) GobDecode(data) (t) GobEncode() (t) Hour() (t) ISOWeek() (t) In(loc) (t) IsDST() (t) IsZero() (t) Local() (t) Location() (t) MarshalBinary() (t) MarshalJSON() (t) MarshalText() (t) Minute() (t) Month() (t) Nanosecond() (t) Round(d) (t) Second() (t) String() (t) Sub(u) (t) Truncate(d) (t) UTC() (t) Unix() (t) UnixMicro() (t) UnixMilli() (t) UnixNano() (t) UnmarshalBinary(data) (t) UnmarshalJSON(data) (t) UnmarshalText(data) (t) Weekday() (t) Year() (t) YearDay() (t) Zone() (t) ZoneBounds() type Timer AfterFunc(d, f) NewTimer(d) (t) Reset(d) (t) Stop() type Weekday (d) String() Source Files Directories Documentation Documentation ¶ Rendered for linux/amd64 windows/amd64 darwin/amd64 js/wasm Overview ¶ Monotonic Clocks Timer Resolution Package time provides functionality for measuring and displaying time. The calendrical calculations always assume a Gregorian calendar, with no leap seconds. Monotonic Clocks ¶ Operating systems provide both a “wall clock,” which is subject to changes for clock synchronization, and a “monotonic clock,” which is not. The general rule is that the wall clock is for telling time and the monotonic clock is for measuring time. Rather than split the API, in this package the Time returned by time.Now contains both a wall clock reading and a monotonic clock reading; later time-telling operations use the wall clock reading, but later time-measuring operations, specifically comparisons and subtractions, use the monotonic clock reading. For example, this code always computes a positive elapsed time of approximately 20 milliseconds, even if the wall clock is changed during the operation being timed: start := time.Now() ... operation that takes 20 milliseconds ... t := time.Now() elapsed := t.Sub(start) Other idioms, such as time.Since(start), time.Until(deadline), and time.Now().Before(deadline), are similarly robust against wall clock resets. The rest of this section gives the precise details of how operations use monotonic clocks, but understanding those details is not required to use this package. The Time returned by time.Now contains a monotonic clock reading. If Time t has a monotonic clock reading, t.Add adds the same duration to both the wall clock and monotonic clock readings to compute the result. Because t.AddDate(y, m, d), t.Round(d), and t.Truncate(d) are wall time computations, they always strip any monotonic clock reading from their results. Because t.In, t.Local, and t.UTC are used for their effect on the interpretation of the wall time, they also strip any monotonic clock reading from their results. The canonical way to strip a monotonic clock reading is to use t = t.Round(0). If Times t and u both contain monotonic clock readings, the operations t.After(u), t.Before(u), t.Equal(u), t.Compare(u), and t.Sub(u) are carried out using the monotonic clock readings alone, ignoring the wall clock readings. If either t or u contains no monotonic clock reading, these operations fall back to using the wall clock readings. On some systems the monotonic clock will stop if the computer goes to sleep. On such a system, t.Sub(u) may not accurately reflect the actual time that passed between t and u. The same applies to other functions and methods that subtract times, such as Since, Until, Time.Before, Time.After, Time.Add, Time.Equal and Time.Compare. In some cases, you may need to strip the monotonic clock to get accurate results. Because the monotonic clock reading has no meaning outside the current process, the serialized forms generated by t.GobEncode, t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic clock reading, and t.Format provides no format for it. Similarly, the constructors time.Date, time.Parse, time.ParseInLocation, and time.Unix, as well as the unmarshalers t.GobDecode, t.UnmarshalBinary. t.UnmarshalJSON, and t.UnmarshalText always create times with no monotonic clock reading. The monotonic clock reading exists only in Time values. It is not a part of Duration values or the Unix times returned by t.Unix and friends. Note that the Go == operator compares not just the time instant but also the Location and the monotonic clock reading. See the documentation for the Time type for a discussion of equality testing for Time values. For debugging, the result of t.String does include the monotonic clock reading if present. If t != u because of different monotonic clock readings, that difference will be visible when printing t.String() and u.String(). Timer Resolution ¶ Timer resolution varies depending on the Go runtime, the operating system and the underlying hardware. On Unix, the resolution is ~1ms. On Windows version 1803 and newer, the resolution is ~0.5ms. On older Windows versions, the default resolution is ~16ms, but a higher resolution may be requested using golang.org/x/sys/windows.TimeBeginPeriod. Index ¶ Constants func After(d Duration) <-chan Time func Sleep(d Duration) func Tick(d Duration) <-chan Time type Duration func ParseDuration(s string) (Duration, error) func Since(t Time) Duration func Until(t Time) Duration func (d Duration) Abs() Duration func (d Duration) Hours() float64 func (d Duration) Microseconds() int64 func (d Duration) Milliseconds() int64 func (d Duration) Minutes() float64 func (d Duration) Nanoseconds() int64 func (d Duration) Round(m Duration) Duration func (d Duration) Seconds() float64 func (d Duration) String() string func (d Duration) Truncate(m Duration) Duration type Location func FixedZone(name string, offset int) *Location func LoadLocation(name string) (*Location, error) func LoadLocationFromTZData(name string, data []byte) (*Location, error) func (l *Location) String() string type Month func (m Month) String() string type ParseError func (e *ParseError) Error() string type Ticker func NewTicker(d Duration) *Ticker func (t *Ticker) Reset(d Duration) func (t *Ticker) Stop() type Time func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time func Now() Time func Parse(layout, value string) (Time, error) func ParseInLocation(layout, value string, loc *Location) (Time, error) func Unix(sec int64, nsec int64) Time func UnixMicro(usec int64) Time func UnixMilli(msec int64) Time func (t Time) Add(d Duration) Time func (t Time) AddDate(years int, months int, days int) Time func (t Time) After(u Time) bool func (t Time) AppendBinary(b []byte) ([]byte, error) func (t Time) AppendFormat(b []byte, layout string) []byte func (t Time) AppendText(b []byte) ([]byte, error) func (t Time) Before(u Time) bool func (t Time) Clock() (hour, min, sec int) func (t Time) Compare(u Time) int func (t Time) Date() (year int, month Month, day int) func (t Time) Day() int func (t Time) Equal(u Time) bool func (t Time) Format(layout string) string func (t Time) GoString() string func (t *Time) GobDecode(data []byte) error func (t Time) GobEncode() ([]byte, error) func (t Time) Hour() int func (t Time) ISOWeek() (year, week int) func (t Time) In(loc *Location) Time func (t Time) IsDST() bool func (t Time) IsZero() bool func (t Time) Local() Time func (t Time) Location() *Location func (t Time) MarshalBinary() ([]byte, error) func (t Time) MarshalJSON() ([]byte, error) func (t Time) MarshalText() ([]byte, error) func (t Time) Minute() int func (t Time) Month() Month func (t Time) Nanosecond() int func (t Time) Round(d Duration) Time func (t Time) Second() int func (t Time) String() string func (t Time) Sub(u Time) Duration func (t Time) Truncate(d Duration) Time func (t Time) UTC() Time func (t Time) Unix() int64 func (t Time) UnixMicro() int64 func (t Time) UnixMilli() int64 func (t Time) UnixNano() int64 func (t *Time) UnmarshalBinary(data []byte) error func (t *Time) UnmarshalJSON(data []byte) error func (t *Time) UnmarshalText(data []byte) error func (t Time) Weekday() Weekday func (t Time) Year() int func (t Time) YearDay() int func (t Time) Zone() (name string, offset int) func (t Time) ZoneBounds() (start, end Time) type Timer func AfterFunc(d Duration, f func()) *Timer func NewTimer(d Duration) *Timer func (t *Timer) Reset(d Duration) bool func (t *Timer) Stop() bool type Weekday func (d Weekday) String() string Examples ¶ After Date Duration Duration.Abs Duration.Hours Duration.Microseconds Duration.Milliseconds Duration.Minutes Duration.Nanoseconds Duration.Round Duration.Seconds Duration.String Duration.Truncate FixedZone LoadLocation Location Month NewTicker Parse ParseDuration ParseInLocation Since Sleep Tic…