Guide · Open source
How to use robfig/cron in Go: schedule jobs in code
Updated · written with AI from the project's own documentation and checked against our catalogue data
robfig/cron is an MIT-licensed Go library that lets your Go program run its own functions on a recurring schedule, using the cron timing format familiar from Linux. This guide is for Go developers who want periodic tasks inside an application instead of separate system crontab entries. By the end you will know how to install the v3 release, choose a parser for the seconds field, and understand the interceptors for panic recovery and skipping overlapping runs.
robfig/cronrobfig/cron · ★ 14.2k · MIT Install options & downloads Quick start
- 1Install the library. Run go get github.com/robfig/cron/v3@v3.0.0 in your Go module. You need Go 1.11 or later.
- 2Import the package. Add import "github.com/robfig/cron/v3" to the file where you schedule jobs.
- 3Create a Cron instance. Call cron.New() for the standard five-field format, or pass cron.WithSeconds() if you need seconds.
- 4Register a job. Call AddFunc or AddJob with a schedule string and the function you want to run.
- 5Add interceptors if needed. Use cron.WithChain with cron.Recover to recover panics, or add delay or skip wrappers for overlapping runs.
- 6Start the scheduler. Call Start() to begin running jobs, and handle shutdown in your application.
What robfig/cron does and when to use it
You import robfig/cron into your Go code and register jobs with a schedule string. Your program then runs those functions on the schedule, so the timing lives in code rather than in system cron entries.
The README positions it for Go developers who need periodic tasks inside an application, and for teams that want job schedules managed in code rather than a system crontab.
- Good fit: periodic tasks inside a Go application, schedules kept in version-controlled code, the standard five-field cron format or the optional seconds field.
- Poor fit: non-Go projects (the README gives no other language bindings), distributed scheduling across many servers (the README does not describe clustering or persistence), or a one-off system job where the OS crontab is simpler.
Install robfig/cron v3 with go get
The README says v3 is the current version. Requirements: Go 1.11 or later, because the library uses Go Modules. To download the tagged v3 release, run the command below, then import the library in your program.
Callers must import the v3 path, not the old gopkg.in path.
- Prerequisite: Go 1.11 or later.
- Import path: github.com/robfig/cron/v3
go get github.com/robfig/cron/v3@v3.0.0Understand the cron schedule format
By default, robfig/cron uses the standard cron format, where the first field is minute, as used by the Linux cron utility. The optional seconds field is opt-in. The README notes that the year field, which Quartz supports, is not supported.
The library also accepts the Quartz format if you opt into it. The original versions included an optional seconds field that was non-standard, so v3 changed the default.
- Default: standard five-field cron format, first field is minute.
- Opt in to a required seconds field with cron.WithSeconds().
- Opt in to an optional seconds field with a custom parser (see the example below).
Configure seconds, timezones and options on construction
Since v3, the Cron type takes functional options when you create it, rather than setting fields or calling setters. If you need the old v1 behavior of an optional seconds field, the README shows how to build a custom parser.
For timezones, the README recommends CRON_TZ to set the timezone of a single schedule, and says the legacy TZ= prefix still works.
- cron.New(cron.WithSeconds()) makes the seconds field required.
- cron.WithParser with cron.SecondOptional makes it optional.
- CRON_TZ is the recommended prefix for a per-schedule timezone; TZ= is still supported.
// Seconds field, required
cron.New(cron.WithSeconds())
// Seconds field, optional
cron.New(cron.WithParser(cron.NewParser(
cron.SecondOptional | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor,
)))Add panic recovery and overlap handling with interceptors
Interceptors are added with the Chain and JobWrapper types. By default, the library no longer recovers panics in jobs, because the README says recovering can be surprising. To opt in, wrap the Cron with cron.Recover and a logger.
The README lists other interceptors: delay a job if the previous run has not finished, skip a job in that case, log each invocation, and get notified when jobs complete.
- Recover panics: cron.Recover(logger), or cron.DefaultLogger.
- Delay or skip a run if the previous one has not completed.
- Log each job invocation, or get notified when jobs complete.
cron.New(cron.WithChain(
cron.Recover(logger), // or use cron.DefaultLogger
))Use logging with robfig/cron
Logging uses an interface compatible with the go-logr/logr project, so you can pass in a structured logger. If you want the Info messages from a standard Go logger, the README provides a wrapper around *log.Logger.
- Use cron.WithLogger to set a logger.
- Use cron.VerbosePrintfLogger(logger) to wrap a *log.Logger so Info messages appear.
- cron.WithVerboseLogger was removed in v3.
cron.New(
cron.WithLogger(cron.VerbosePrintfLogger(logger)))Upgrading from an earlier version
v3 is backwards incompatible with both v1 and v2. The README lists the changes you need to make: the import path, the seconds field default, the way options are set, and panic recovery. Code that set Cron.ErrorLogger or called Cron.SetLocation must provide those values on construction instead.
The v2 branch is listed as an older branch, and v2 is covered by the same backwards-incompatibility notes.
- Change the import to github.com/robfig/cron/v3.
- Restore the seconds field with a custom parser if your code relied on v1 behavior.
- Move ErrorLogger and location settings into construction options.
- Add cron.Recover if you depended on panics being recovered.
What people use it for
- Run a cleanup function inside a Go web service every hour without a separate system crontab entry.
- Send a periodic report from a Go application at a fixed time, with the timezone set using CRON_TZ.
- Poll an external API every few seconds with the seconds field enabled, skipping a run if the last one is still busy.
- Keep all job schedules in version-controlled Go code so changes go through the same review as the rest of the app.
Frequently asked questions
Is robfig/cron free to use?
Yes, the library is released under the MIT licence, according to the analysis for this listing. Check the LICENSE file in the repository for the full terms.
What version of Go do I need for robfig/cron?
The README says it requires Go 1.11 or later, because the library uses Go Modules. Install the v3 release with go get github.com/robfig/cron/v3@v3.0.0.
Does robfig/cron support the seconds field?
Yes. By default it uses the standard five-field format. You can opt into a required seconds field with cron.WithSeconds(), or an optional one with a custom parser.
Does robfig/cron recover from panics in jobs?
Not by default in v3. The README says you can opt in with cron.Recover inside cron.WithChain. Without it, a panic in a job is not recovered by the library.
How does robfig/cron compare to gocron?
The README does not compare the two. Comparable projects listed for this item include gocron and go-co-op/gocron, so evaluate each against your needs, such as persistence or distributed scheduling, which the robfig/cron README does not describe.
Can robfig/cron run jobs across multiple servers?
The README does not describe clustering or persistence. If you need distributed scheduling, look for a tool that documents those features, or use the OS crontab on each machine.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use robfig/cron if you are writing a Go application and want recurring tasks defined in code, with standard cron syntax and optional seconds. Pick something else if your project is not in Go, if you need jobs coordinated across many servers, or if a single system job is all you need, where the OS crontab is simpler.
Install options & downloads