# chrono: the timezone-aware date and time crate for Rust

> chrono handles dates and times in the proleptic Gregorian calendar, with timezone-aware types by default and timezone data kept out of the binary. It suits Rust services that parse, format and compare timestamps, and it is a poor fit for anyone who needs a full tz database bundled in.

**chronotope/chrono** — Date and time library for Rust

- Repository: https://github.com/chronotope/chrono
- Stars: 3,916 · Forks: 615
- Language: Rust
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/chronotope-chrono

## What chrono solves for Rust programs that handle time

Rust's standard library has no calendar type. Any program that reads a timestamp from a database, renders a date for a user, or compares two instants has to build that logic itself or take a dependency. chrono is that dependency for a large part of the ecosystem. The README states the aim plainly: to provide all functionality needed to do correct operations on dates and times in the proleptic Gregorian calendar.

The design decision that matters most is in the first bullet of the README. DateTime is timezone-aware by default, and timezone-naive types are separate. That is the opposite of the common pattern where a naive local timestamp is the default and the offset is an afterthought. If you have ever debugged a service that stored local wall-clock time and then moved a server between regions, you know why the default matters.

The second decision is about failure. Operations that may produce an invalid or ambiguous date and time return Option or MappedLocalTime rather than panicking or silently picking an offset. Ambiguity is real: during a daylight saving transition, one wall-clock reading can map to two instants, or to none. The type system forces the caller to say what should happen.

Who is it for? Backend services, CLI tools, log processors, schedulers, anything that serialises timestamps and has to read them back. It is also for library authors who need a date type in their public API and do not want to write one.

## DateTime, MappedLocalTime and the strftime-style format strings

The core type is DateTime, documented at docs.rs/chrono/latest/chrono/struct.DateTime.html. A DateTime carries a timezone offset alongside the calendar fields, which is what makes it timezone-aware. The naive counterparts exist for cases where no offset applies, such as a birthday or a recurring schedule expressed in local time.

Parsing and formatting use an strftime inspired syntax, and the README describes it as configurable. That is a deliberate choice: strftime is familiar to anyone coming from C, Python or Ruby, so the format strings transfer. The cost is that strftime has a long and inconsistent history, and chrono's variant is its own implementation rather than a binding to the platform's.

The Local timezone works with the current timezone of the OS. That is the mechanism behind the clock feature. It does not carry a copy of the IANA database. Instead, the clock feature pulls in iana-time-zone, per the feature list in Cargo.toml, to find out what the OS thinks the local zone is. The README is explicit that timezone data is not shipped with chrono by default, to limit binary sizes, and points at the companion crate Chrono-TZ or tzfile for full timezone support.

That split is the central architectural fact about chrono. The crate gives you the offset machinery and the calendar arithmetic. The zone database is somebody else's crate.

## Adding chrono to a Cargo.toml

The crate is published on crates.io as chrono, at version 0.4.45 per the repository's Cargo.toml. Adding it is a single dependency line. The default feature set is clock, std, oldtime and wasmbind, so a plain add pulls in the local timezone support and the wasm binding. If you want to trim that, you disable default features and name the ones you need.

```toml
[dependencies]
chrono = "0.4.45"
```

With the default features in place, reading the current time uses the Local timezone, which the README describes as working with the current timezone of the OS. Formatting uses the strftime inspired specifiers, and the README describes that syntax as configurable. The output is a string, which means the alloc or std feature has to be on, and both are in the default set.

If you only need the system clock and not the OS timezone, the now feature is the smaller dependency. The README lists now as a subset of clock: clock enables reading the local timezone, and now enables reading the system time. Choosing now instead of clock drops the iana-time-zone dependency and the winapi dependency on Windows.

For a fixed offset, you do not need the clock feature at all. A DateTime with a known offset can be constructed and formatted without touching the OS. That is the configuration to reach for in a container where the local timezone is UTC and you want the build to be reproducible regardless of the host.

If you need to convert to a named zone such as Asia/Tokyo, chrono alone will not do it. The README points at Chrono-TZ or tzfile, and one of those crates belongs in the same dependency block.

## Leap seconds, calendar range and the timezone data you do not get

The README's limitations section is short and worth reading before adoption. Only the proleptic Gregorian calendar is supported, meaning it is extended backwards to dates before the calendar existed. If you need Julian dates, Islamic, Hebrew or Chinese calendars, chrono will not give them to you.

Date types are limited to about +/- 262,000 years from the common epoch, and time types to nanosecond accuracy. Those bounds are wide enough that most applications never approach them, but a simulation or an astronomy tool might.

The leap second limitation is the one that catches people. The README says leap seconds can be represented, but chrono does not fully support them, and links to a Leap Second Handling section on the NaiveTime docs. In practice this means a leap second is a value you can hold, not a value the arithmetic treats correctly. If your domain is satellite tracking or anything that counts SI seconds across a leap second, this is a real gap and you should read that documentation page before deciding.

The other limitation is the one already mentioned: no timezone data. The README's own recommendation is Chrono-TZ or tzfile. A service that has to convert a timestamp to Asia/Tokyo needs one of those crates in addition to chrono. That is a second dependency to audit and update when the tz database changes.

## chrono compared with the time crate

The natural alternative in Rust is time, the crate that chrono's own oldtime feature used to exist for compatibility with at version 0.1. The README notes that oldtime no longer has any effect, which is a small historical marker of how the two crates diverged.

The difference in approach is about defaults and scope. chrono leads with timezone-aware DateTime and treats the naive types as the separate case. It also carries the strftime-style formatting syntax, which is a compatibility argument for anyone porting code from C, Python or Ruby. The time crate takes a different route on formatting and on how offsets are modelled, and it does not carry chrono's legacy surface.

Neither crate ships the IANA database, so the timezone question is separate from the choice between them. What you are really choosing is the API shape, the formatting syntax and the set of types that appear in your public interfaces. If your codebase already passes chrono::DateTime across module boundaries, switching is a rewrite of those signatures, not a dependency swap.

A second alternative worth naming is doing the arithmetic yourself on Unix timestamps with plain integers. That works until you need a calendar, at which point you are reimplementing chrono badly.

## Maintenance, MSRV and the dual licence

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent and small: v0.4.45 on 2026-06-04, v0.4.44 on 2026-02-23, v0.4.43 on 2026-01-14. The version numbers stay in the 0.4 line, which means the crate has been stable at that major version for a long time and upgrades are patch-level in practice.

The stated MSRV is Rust 1.62.0, and the README says it is explicitly tested in CI. It also says the MSRV may be bumped in minor releases, but not lightly. For a team pinned to an older toolchain, that is a commitment you can plan around rather than a surprise.

The upgrade cost is mostly in feature flags. Cargo.toml notes that rkyv-16, rkyv-32 and rkyv-64 are mutually exclusive, and that the plain rkyv feature is deprecated in favour of the numbered ones. The unstable-locales feature is documented as possibly changing or being removed in a patch release, which is a warning to keep it out of anything you cannot rebuild quickly. There is also a CI note in Cargo.toml reminding maintainers to adjust ALL_NON_EXCLUSIVE_FEATURES when adding a feature, which tells you the feature matrix is actively managed.

On licensing, Cargo.toml declares MIT OR Apache-2.0, and the README confirms the project is licensed under either of the Apache License, Version 2.0 or the MIT License, at your option. That is the standard permissive pairing in the Rust ecosystem. The repository metadata reports the licence as NOASSERTION, which is a tooling artefact rather than a different grant; the files themselves state the dual licence. If your organisation requires a specific one of the two, pick it explicitly in your attribution rather than relying on the OR. This is not legal advice.

## Conclusion

Adopt chrono for Rust code that needs timezone-aware parsing, formatting and arithmetic without shipping a tz database. Do not adopt it if you need the full IANA timezone set inside the crate, leap-second correctness, or a calendar other than the proleptic Gregorian one. Before you commit, check three things: which crate features you actually need, since the default set includes clock, std, oldtime and wasmbind; whether your toolchain meets the stated MSRV of Rust 1.62.0; and whether Chrono-TZ or tzfile belongs in your dependency list, because chrono itself ships no timezone data.

## FAQ

### How do you use chrono in a Rust project?

Add chrono to your dependencies and use the DateTime type, which is timezone-aware by default, with separate timezone-naive types for cases where no offset applies. Formatting uses an strftime inspired syntax, and the Local timezone works with the current timezone of the OS when the clock feature is enabled.

### How does chrono compare with the time crate?

The README notes that the oldtime feature, which used to offer compatibility with the time 0.1 crate, no longer has any effect. The two crates differ in API shape and formatting syntax; neither ships timezone data, so the IANA database question is separate from the choice between them.

### Does chrono ship timezone data?

No. The README states that timezone data is not shipped with chrono by default, to limit binary sizes, and recommends the companion crate Chrono-TZ or tzfile for full timezone support.

### What Rust version does chrono require?

The Minimum Supported Rust Version is currently Rust 1.62.0, and the README says it is explicitly tested in CI and may be bumped in minor releases, though not lightly.

### Does chrono support leap seconds?

The README lists leap seconds under limitations: they can be represented, but chrono does not fully support them, and it links to a Leap Second Handling section on the NaiveTime documentation.

### What licence is chrono under?

Cargo.toml declares MIT OR Apache-2.0, and the README states the project is licensed under either the Apache License, Version 2.0 or the MIT License, at your option.

## Sources

- [chronotope/chrono on GitHub](https://github.com/chronotope/chrono)
- [Issues](https://github.com/chronotope/chrono/issues)
- [README](https://github.com/chronotope/chrono/blob/main/README.md)
- [Releases](https://github.com/chronotope/chrono/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chronotope-chrono