Time en Golang: Now, Sleep, Format, Parse y duraciones

Lo básico en un programa

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Now()

	time.Sleep(50 * time.Millisecond)

	elapsed := time.Since(start)
	fmt.Println("slept at least 50ms:", elapsed >= 50*time.Millisecond)

	t := time.Date(2026, time.September, 23, 14, 30, 0, 0, time.UTC)
	fmt.Println(t)
	fmt.Println(t.Format("2006-01-02 15:04"))
	fmt.Println(t.Format("Monday, January 2, 2006"))
	fmt.Println("in 90 minutes:", t.Add(90*time.Minute).Format(time.Kitchen))
}

time.Now() devuelve la hora local actual, time.Sleep pausa la goroutine actual, time.Since mide el tiempo transcurrido y time.Date construye un momento concreto. El resto de esta página trata cada pieza por separado. Los ejemplos usan fechas fijas y UTC para que su salida sea la misma dondequiera que los ejecutes.

Sleep y Duration

Un time.Duration es un int64 que cuenta nanosegundos. El paquete define constantes para construir valores legibles:

No existe time.Day, porque un día no siempre dura 24 horas cuando una zona horaria cambia por el horario de verano. Usa AddDate para los días de calendario (más abajo).

package main

import (
	"fmt"
	"time"
)

func main() {
	d := 90 * time.Minute
	fmt.Println(d)                      // 1h30m0s
	fmt.Println(d.Hours(), d.Minutes()) // float64 values
	fmt.Println(2*time.Hour + 15*time.Second)

	// Multiplying by a variable needs a conversion: int * Duration does not compile.
	retries := 3
	backoff := time.Duration(retries) * 200 * time.Millisecond
	fmt.Println("backoff:", backoff)

	// Parse a duration from a string (for flags and config files).
	timeout, err := time.ParseDuration("1m30s")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("timeout:", timeout, "=", timeout.Seconds(), "seconds")

	// Round and truncate a measured duration for display.
	measured := 1234567891 * time.Nanosecond
	fmt.Println(measured, measured.Round(time.Millisecond), measured.Truncate(time.Second))
}

Dos bugs habituales vienen de que Duration sea un entero:

• time.Sleep(5) duerme 5 nanosegundos. Multiplica siempre por una unidad: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) no compila cuando n es una variable int. Conviértela: time.Duration(n) * time.Second. Una constante como 5 funciona sin conversión porque las constantes sin tipo se adaptan al tipo Duration.

ParseDuration acepta ns, us (o µs), ms, s, m y h, combinados como "2h45m" o "1.5s". No tiene unidad para los días.

Formato: el layout de referencia 2006-01-02

Go no usa %Y-%m-%d ni yyyy-MM-dd. Un layout es la hora de referencia

Mon Jan 2 15:04:05 MST 2006

escrita tal como quieres que se vea tu salida. Los valores se eligieron para que cada uno sea único: mes 1, día 2, hora 3 (o 15), minuto 4, segundo 5, año 6 (2006), desfase de zona -7 (-0700). Léelo como 01/02 03:04:05PM '06 -0700.

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.March, 5, 9, 7, 3, 250_000_000, time.UTC)

	layouts := []string{
		"2006-01-02",
		"02/01/2006",
		"01/02/06",
		"Jan 2, 2006",
		"Monday 2 January 2006",
		"15:04:05",
		"3:04 PM",
		"2006-01-02T15:04:05.000Z07:00",
		time.RFC3339,
		time.DateTime,
		time.RFC1123,
	}
	for _, l := range layouts {
		fmt.Printf("%-32q %s\n", l, t.Format(l))
	}
}

Los tokens de layout que más vas a necesitar:

Layouts predefinidos:

El error clásico es escribir un layout con los números equivocados, por ejemplo "2023-01-01". Go no lo rechaza. Copia los caracteres que no reconoce y sustituye los que sí: cada 2 es el día, 3 es la hora en formato de 12 horas y los dos 01 son el mes, así que el 5 de marzo a las 9:07 se formatea como 5059-03-03. Un layout como "YYYY-MM-DD" no contiene ningún token y se imprime tal cual. Si las fechas formateadas se ven raras, comprueba que el layout usa exactamente los valores de referencia.

Parsear strings a horas

time.Parse(layout, value) usa los mismos layouts y devuelve un error que tienes que comprobar:

package main

import (
	"fmt"
	"time"
)

func main() {
	t, err := time.Parse("2006-01-02 15:04", "2026-09-23 18:45")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t, "| location:", t.Location())

	// A string with an offset keeps that offset.
	t2, err := time.Parse(time.RFC3339, "2026-09-23T18:45:00+02:00")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t2, "| in UTC:", t2.UTC())

	// Interpret a zone-less string in a specific zone.
	tokyo := time.FixedZone("JST", 9*60*60)
	t3, err := time.ParseInLocation(time.DateTime, "2026-09-23 18:45:00", tokyo)
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t3, "| in UTC:", t3.UTC())

	// A wrong input produces a descriptive error.
	_, err = time.Parse(time.DateOnly, "23/09/2026")
	fmt.Println("error:", err)
}

Sin zona en la entrada, Parse devuelve UTC. El mismo string de hora de reloj puede significar instantes distintos según la zona, y por eso existe ParseInLocation. El mensaje de error nombra la parte que no coincidió, lo que ayuda al depurar un layout.

Zonas horarias

Un time.Time es un instante más una ubicación que se usa para mostrarlo. Cambiar la ubicación con In cambia cómo se imprime, no qué momento es.

package main

import (
	"fmt"
	"time"
	_ "time/tzdata" // embed the zone database so LoadLocation works anywhere
)

func main() {
	meeting := time.Date(2026, time.September, 23, 15, 0, 0, 0, time.UTC)

	ny, err := time.LoadLocation("America/New_York")
	if err != nil {
		fmt.Println("load location:", err)
		return
	}
	india := time.FixedZone("IST", 5*60*60+30*60) // +05:30, no DST rules

	fmt.Println("UTC:     ", meeting.Format(time.RFC1123))
	fmt.Println("New York:", meeting.In(ny).Format(time.RFC1123))
	fmt.Println("India:   ", meeting.In(india).Format(time.RFC1123))
	fmt.Println("same instant:", meeting.Equal(meeting.In(ny)))
}

• time.UTC siempre está disponible. Guarda y transmite las horas en UTC (o en RFC 3339 con desfase) y convierte solo para mostrarlas.
• time.Local es la zona de la máquina. En servidores y contenedores suele ser UTC, y en un portátil no, así que el código que depende de ella se comporta distinto en cada sitio.
• time.LoadLocation("Europe/Berlin") lee la base de datos IANA del sistema operativo. Las imágenes de contenedor mínimas a menudo no la tienen, y entonces la llamada devuelve un error. El import vacío _ "time/tzdata" incrusta la base de datos en tu binario (unos 450 KB) para que siempre funcione. Maneja siempre el error.
• time.FixedZone(name, offsetSeconds) crea una zona con un desfase constante. No tiene reglas de horario de verano, así que úsala para desfases que has recibido, no para regiones con nombre.

Aritmética y comparación

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Date(2026, time.January, 31, 10, 0, 0, 0, time.UTC)
	end := time.Date(2026, time.March, 1, 12, 30, 0, 0, time.UTC)

	fmt.Println("difference:", end.Sub(start))
	fmt.Println("in days:   ", int(end.Sub(start).Hours()/24))

	fmt.Println("+36h:      ", start.Add(36*time.Hour).Format(time.DateTime))
	fmt.Println("-1 week:   ", start.AddDate(0, 0, -7).Format(time.DateOnly))
	fmt.Println("+1 month:  ", start.AddDate(0, 1, 0).Format(time.DateOnly)) // Jan 31 + 1 month

	fmt.Println("before:", start.Before(end), "after:", start.After(end), "equal:", start.Equal(end))

	// Start of the day, and parts of a date.
	y, m, d := end.Date()
	midnight := time.Date(y, m, d, 0, 0, 0, 0, end.Location())
	fmt.Println("midnight:", midnight.Format(time.DateTime))
	fmt.Println("weekday:", end.Weekday(), "day of year:", end.YearDay())

	// Unix timestamps.
	fmt.Println("unix:", start.Unix(), "ms:", start.UnixMilli())
	fmt.Println("from unix:", time.Unix(1_790_000_000, 0).UTC())
}

Cosas en las que fijarse en la salida:

• AddDate(0, 1, 0) sobre el 31 de enero da el 3 de marzo, no el 28 de febrero. Go suma un mes para obtener "31 de febrero" y luego normaliza el exceso. Si necesitas "el mismo día del mes siguiente, ajustado al último día", escribe tú esa lógica.
• Sub devuelve un Duration, que llega como mucho a unos 292 años. Para diferencias en días de calendario, compara las fechas a medianoche UTC y divide entre 24 horas.
• Para obtener el inicio del día, reconstruye la hora a partir de Date(). t.Truncate(24 * time.Hour) redondea respecto a la hora cero en UTC, así que da una respuesta equivocada en cualquier zona que no sea UTC.

Compara con Equal, Before y After, nunca con ==. time.Now() incluye una lectura del reloj monotónico, que sirve para que time.Since siga siendo correcto si se ajusta el reloj del sistema. == compara también esa lectura y la ubicación, así que dos valores Time del mismo instante pueden ser distintos. Por la misma razón, no uses time.Time como clave de un map sin normalizarlo antes (t.UTC().Round(0) quita la lectura monotónica).

El time.Time cero es el 1 de enero del año 1, a las 00:00 UTC. Compruébalo con t.IsZero().

Medir el tiempo transcurrido

start := time.Now()
doWork()
log.Printf("doWork took %v", time.Since(start))

time.Since(start) equivale a time.Now().Sub(start), y time.Until(deadline) a deadline.Sub(time.Now()). Los dos usan el reloj monotónico cuando está disponible, así que son seguros frente a cambios del reloj del sistema. Para hacer benchmarks de código, usa el soporte de benchmarks de Go del paquete testing en lugar de medir a mano.

Timers y tickers

time.After(d) devuelve un channel que recibe una vez pasado d. Un time.Timer es lo mismo con un método Stop. Un time.Ticker entrega un valor cada periodo hasta que lo detienes.

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(20 * time.Millisecond)
	defer ticker.Stop()

	done := time.NewTimer(110 * time.Millisecond)
	defer done.Stop()

	ticks := 0
	for {
		select {
		case <-ticker.C:
			ticks++
			fmt.Println("tick", ticks)
			if ticks == 3 {
				fmt.Println("got three ticks, stopping early")
				return
			}
		case <-done.C:
			fmt.Println("timer fired first")
			return
		}
	}
}

Los tres ticks a los 20, 40 y 60 ms llegan mucho antes que el timer de 110 ms, así que el programa se detiene tras el tercer tick. time.AfterFunc(d, f) ejecuta f en su propia goroutine pasado d, lo que viene bien para trabajo diferido puntual.

Desde Go 1.23, los timers y tickers a los que ya nada hace referencia se recolectan aunque nunca llames a Stop, y el channel de un timer detenido o reiniciado ya no entrega un valor obsoleto. Llamar a Stop con defer sigue siendo la forma clara de decir que la vida del ticker ha terminado. Cuando un límite de tiempo se aplica a una operación entera y no a una sola espera, un context.WithTimeout suele leerse mejor que un timer.

Time en JSON

time.Time se serializa y deserializa automáticamente como strings RFC 3339 en JSON, con precisión de nanosegundos:

type Event struct {
	Name string    `json:"name"`
	At   time.Time `json:"at"`
}
// {"name":"deploy","at":"2026-09-23T14:30:00Z"}

Un string JSON con otro formato falla al deserializar. Para timestamps Unix o formatos propios, guarda un int64 o un string y convierte, o define un tipo con su propio UnmarshalJSON.

Errores comunes

• time.Sleep(1) o time.Sleep(n) con un número a secas. Eso son nanosegundos.
• Layouts con los dígitos equivocados. "2023-01-01" o "YYYY-MM-DD" no son layouts. Usa "2006-01-02".
• Confundir minutos y meses. Los minutos son 04 y los meses 01. "15:01" imprime la hora y luego el mes, no el minuto.
• Comparar con ==. Usa Equal.
• Depender de time.Local. Cambia de una máquina a otra. Sé explícito con time.UTC o con una ubicación cargada.
• Ignorar el error de LoadLocation o de Parse. Los dos fallan con entradas reales. Un Parse fallido devuelve la hora cero, que se imprime como el año 1, y un LoadLocation fallido devuelve una ubicación nil que hace que t.In(loc) provoque un panic.