Jiff 1.0 brings a new datetime model to the Rust ecosystem
Andrew Gallant releases Jiff 1.0, a Rust datetime library inspired by JavaScript's Temporal that prioritizes time zone safety and API clarity.
Andrew Gallant has announced the 1.0 release of Jiff, a new datetime library for the Rust programming language. The library aims to resolve long-standing confusion in the Rust ecosystem regarding date and time handling by offering a design heavily inspired by JavaScript’s Temporal proposal. This stable release marks a commitment to long-term API compatibility for projects that depend on it.
What happened
For years, Rust developers have debated whether to use chrono or time for datetime operations. Gallant noted that both libraries had reached a local maximum in their design, making significant improvements difficult without breaking changes. He found the existing APIs confusing, particularly when dealing with local time conversion, system time zone databases, and calendar arithmetic. Rather than trying to convince existing maintainers to adopt radically different directions, he built Jiff to encapsulate domain complexity and guide users toward correct usage.
The library has already seen substantial adoption in production tools before reaching version 1.0. Projects such as uv, Cargo, Starship, fd, Nushell, mise, Jujutsu, and uutils/coreutils currently use Jiff. It also serves as the basis for a Temporal implementation in AWS LLRT. With this widespread usage, Gallant declared the API stable, promising to avoid semver-incompatible releases unless critical defects are found. This stability is intended to make Jiff a safe public dependency for other libraries in the ecosystem.
How it works
Jiff models datetime handling as an onion of layers, starting from simple civil dates and times and building up to fully zoned datetimes. At the base are civil::Date and civil::Time, which represent plain Gregorian dates and clock times unattached to any location. These combine into a civil::DateTime. Above this layer sits the Timestamp, which represents an unambiguous instant in time as nanoseconds since the Unix epoch. The outermost layer is the ZonedDateTime, which combines a timestamp, a civil datetime, and a TimeZone to represent a specific moment in a specific geographic region.
The library draws heavy inspiration from JavaScript’s Temporal standard library, translating its API concepts into Rust idioms. For example, Temporal’s Duration type is named Span in Jiff to avoid confusion with Rust’s standard library std::time::Duration. Similarly, Temporal’s Instant is called Timestamp to distinguish it from std::time::Instant. Civil types in Temporal are referred to as "civil" in Jiff. While not a one-to-one implementation, Jiff allows developers familiar with Temporal to find the API straightforward. It automatically handles common pitfalls like daylight saving time transitions by putting time zone rules at the center of its design.
Key details
- Jiff 1.0 commits to indefinite API stability to support its role as an ecosystem building block.
- The library is pronounced like "gif" with a soft "g," similar to the word "gem."
- Jiff uses the term
Spanfor durations andTimestampfor instants to prevent naming conflicts with Rust standard library types. - Time zones are defined using IANA Time Zone Database Identifiers, such as
America/New_YorkorAsia/Tokyo. - The library supports date rounding and calendar arithmetic, allowing operations like rounding a span to the nearest day relative to a specific date.
- Jiff only supports the Gregorian calendar and limits its datetime range to +/- 9999 years.
Why it matters
Datetime handling is notoriously error-prone because it sits at the intersection of computer system time and human civil time. System time relies on Unix time, while human time involves complex rules like leap seconds, daylight saving time, and geographic offsets. Many existing libraries pass this complexity on to the developer, leading to bugs when converting between timestamps and local clocks. Jiff attempts to encapsulate this complexity, making it difficult for users to perform invalid operations or misinterpret time zone data.
For technical leads and engineers building cross-platform tools, having a stable, well-modeled datetime library reduces maintenance burden. By adopting a design that prevents ambiguity during time zone transitions, Jiff helps teams avoid subtle bugs related to clock shifts. Its adoption by major Rust tooling projects suggests it may become the de facto standard for new Rust applications, reducing the fragmentation caused by the previous choice between chrono and time.
What you can do
- Add
jiffandanyhowto your Cargo project to test the API examples provided in the announcement. - Review the mapping between Temporal concepts and Jiff types if you have experience with JavaScript datetime handling.
- Replace legacy datetime logic in your Rust applications with Jiff’s
ZonedDateTimeto ensure correct time zone handling. - Use the
Spantype for calendar arithmetic instead of manual second calculations to improve code readability. - Consult the CHANGELOG to understand the breaking changes between Jiff 0.2 and 1.0 if you are an early adopter.
- Evaluate Jiff for new projects where long-term API stability is a requirement for public dependencies.


