The date library dilemma
You are starting a new Rust project. You need to handle dates. You open Cargo.toml and type chrono. It is the default. Every tutorial uses it. Your database driver expects it. Your HTTP client serializes to it. But then you see a blog post warning about leap seconds, or a colleague mentions time is faster and safer. Now you are stuck. Which one do you pick?
The answer is not just "one is old, one is new." It is about trade-offs between ecosystem inertia and modern design. chrono is the veteran library that grew organically over a decade. It is flexible, widely supported, and slightly messy. time is the modern challenger designed from scratch with strict RFC 3339 compliance, better type safety, and performance as primary goals.
Two philosophies, one problem
Rust's standard library does not include date and time types. The community fills that gap. Two crates dominate the space.
chrono follows a "batteries included" philosophy. It provides a rich set of types: NaiveDate, NaiveTime, NaiveDateTime, DateTime<Tz>, Date, Time. It allows you to mix and match these types. You can add a Duration to a NaiveDateTime. You can convert between timezones easily. This flexibility makes chrono convenient for quick scripts and legacy integration. It also introduces ambiguity. A NaiveDateTime looks like a date and time, but it carries no timezone information. You can accidentally treat a naive time as UTC, leading to subtle bugs.
time follows a "correctness first" philosophy. It separates concerns more strictly. The main type is OffsetDateTime, which bundles date, time, and timezone offset into a single struct. You cannot create an OffsetDateTime without an offset. time forces you to handle errors explicitly. Constructors return Result instead of Option. time uses compile-time macros to validate format strings. This reduces runtime errors but requires more boilerplate.
Think of chrono like a Swiss Army knife with a few extra tools duct-taped on. It works for everything, but the handle is worn and some tools overlap. Think of time like a precision machinist's set. Each tool has a specific shape, fits perfectly, and won't let you cut your finger off. You have to learn the names of the tools, but you get consistent results.
Minimal example
Both crates provide a way to get the current UTC time. The APIs look similar, but the types differ.
use chrono::Utc;
use time::OffsetDateTime;
/// Demonstrates basic usage of chrono and time crates.
fn main() {
// chrono: Utc::now() returns a DateTime<Utc>.
// DateTime<Utc> carries timezone information in the type parameter.
let chrono_now = Utc::now();
println!("chrono: {}", chrono_now);
// time: OffsetDateTime::now_utc() returns an OffsetDateTime.
// OffsetDateTime bundles date, time, and offset in one struct.
let time_now = OffsetDateTime::now_utc();
println!("time: {}", time_now);
}
The output looks identical. Both print an ISO 8601 string. The difference is in the types. chrono's DateTime<Utc> is a generic type parameterized by a timezone trait. time's OffsetDateTime is a concrete struct. This affects performance and API design. chrono uses trait objects or enums internally for timezones, which adds indirection. time stores the offset as a fixed integer, which is more compact and faster.
Under the hood
chrono represents dates as seconds and nanoseconds since the Unix epoch. It uses i64 for seconds and i32 for nanoseconds. This is efficient for arithmetic. However, chrono allows you to create invalid dates. The function NaiveDate::from_ymd panics if you pass an invalid date like February 30. The safe version NaiveDate::from_ymd_opt returns Option<NaiveDate>. Many users ignore the Option and use the panicking version, leading to runtime crashes.
time represents dates as days and seconds since the Unix epoch. It uses i64 for days and i32 for seconds. This layout optimizes for common operations. time forces error handling. The function Date::from_calendar_date returns Result<Date, time::Error>. You cannot create an invalid date without handling the error. time also provides time::macros::format_description! to validate format strings at compile time. If you write a typo in the format, the compiler rejects it. chrono validates format strings at runtime. A typo in chrono causes a panic or incorrect output when you try to parse.
Convention aside: The time community prefers using time::macros::format_description! for all format strings. This catches errors early. The chrono community often uses strftime-style strings like "%Y-%m-%d". These are convenient but error-prone.
Realistic example: Parsing and formatting
Parsing date strings is where the crates diverge significantly. You receive a string from an API and need to parse it into a date type.
use chrono::DateTime;
use time::OffsetDateTime;
/// Parses a date string using chrono.
/// chrono's from_str assumes RFC 3339 format.
fn parse_chrono(s: &str) -> Result<DateTime<chrono::Utc>, chrono::ParseError> {
// chrono parses to a specific type.
// from_str relies on the FromStr trait implementation.
s.parse::<DateTime<chrono::Utc>>()
}
/// Parses a date string using time.
/// time's from_str is strictly RFC 3339.
fn parse_time(s: &str) -> Result<OffsetDateTime, time::Error> {
// time parses to OffsetDateTime.
// from_str is strict and returns a Result.
s.parse::<OffsetDateTime>()
}
/// Formats a date using chrono.
fn format_chrono(dt: &DateTime<chrono::Utc>) -> String {
// chrono uses format! with a strftime-like string.
// The format string is checked at runtime.
dt.format("%Y-%m-%d %H:%M:%S %Z").to_string()
}
/// Formats a date using time.
fn format_time(dt: &OffsetDateTime) -> String {
// time uses format! with a format description.
// The format description can be checked at compile time using macros.
let fmt = time::macros::format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");
time::format_description::parse::parse_formatted(dt, fmt).unwrap_or_else(|_| dt.to_string())
}
chrono's from_str is convenient. It tries to parse RFC 3339. If the string is not RFC 3339, you need parse_from_str with a custom format. chrono's format strings use % codes. time's from_str is strictly RFC 3339. If you need a custom format, you must use time::parse with a format_description. time's format_description is more verbose but type-safe. You can define the description once and reuse it. time also provides time::macros::format_description! to check the description at compile time.
Convention aside: chrono users often write dt.format("%+").to_string() for ISO 8601 output. The %+ code is a shorthand for RFC 3339. time users write dt.to_string() which defaults to RFC 3339. Both work, but time's default is stricter.
Pitfalls and compiler errors
chrono has several pitfalls. The biggest is NaiveDateTime. You can create a NaiveDateTime and treat it as UTC, but it is not. If you pass a NaiveDateTime to a function expecting a timezone-aware date, the compiler might accept it if the function is generic. This leads to bugs where naive times are interpreted as UTC. chrono does not warn you.
Another pitfall is chrono's from_ymd function. It panics on invalid dates. Many users call from_ymd without checking the date. If the date is invalid, the program crashes. The safe version from_ymd_opt returns Option. Users often ignore the Option and use unwrap(), which also panics. chrono makes it easy to panic.
time has fewer pitfalls but a steeper learning curve. time's format_description API is verbose. You need to import time::macros::format_description! and use the correct syntax. If you make a mistake, the compiler rejects it. This is good for safety but annoying for quick scripts. time also had a major breaking change in version 0.3. Code written for time 0.2 does not compile with 0.3. Check your dependencies.
If you try to parse an invalid date with chrono, you get a ParseError. The error message is usually clear. If you try to create an invalid date with time, you get a time::Error. The error message includes the invalid value and the reason. time's errors are more informative.
Don't ignore the Option in chrono. Treat it like a Result or you will get panics at runtime.
Decision matrix
Use chrono when you need to integrate with a large ecosystem of older crates that depend on chrono. Many popular crates like database drivers, HTTP clients, and serialization libraries use chrono types. Switching to time requires writing conversion glue.
Use time when you are starting a new project and want strict RFC 3339 compliance and better type safety. time forces you to handle errors and validates format strings at compile time. This reduces runtime bugs.
Use chrono when you need flexible formatting with strftime-style strings and don't mind the performance cost. chrono's format strings are concise and familiar to developers coming from C or Python.
Use time when performance is critical and you need zero-cost abstractions for date arithmetic. time is generally faster than chrono for parsing, formatting, and arithmetic. time's memory layout is more compact.
Reach for chrono when you are working with legacy codebases where refactoring to time is too expensive. chrono is stable and well-documented. You can find examples for almost any use case.
Pick time when you want the compiler to catch invalid dates at compile time using macros. time's format_description! macro validates format strings. This prevents typos and incorrect formats.
Check your dependencies. If half your stack uses chrono, switching to time means writing conversion glue. Weigh that cost.