Joda-Time in 2026: the finished date library and when you should still add it

Who still needs Joda-Time rather than java.time

The problem Joda-Time solves is narrow and old. The date and time classes shipped with Java before Java SE 8 were awkward to use correctly, and the README describes Joda-Time as "a quality replacement for the Java date and time classes". Its design allows for multiple calendar systems while keeping a simple API, with ISO8601 as the default and the Gregorian, Julian, Buddhist, Coptic, Ethiopic and Islamic systems also included. Supporting classes cover time zones, durations, formatting and parsing.

The audience is therefore a specific one. Projects compiled against older JDKs, and Android applications that cannot raise their minimum API level, are the readers this library was written for. If your code must run where java.time does not exist, Joda-Time is not a legacy curiosity; it is the practical option.

The project itself is explicit about its status. The README states that Joda-Time "is no longer in active development except to keep timezone data up to date", and repeats later that it is considered "a largely finished project" with no major enhancements planned. That is not abandonment. The last push to the repository was on 2026-09-21, and releases v2.14.2, v2.14.3 and v2.14.4 arrived during 2026, which is consistent with the stated policy of shipping timezone updates. Judge it as a stable library receiving data maintenance, not as a project adding features.

Immutability, calendar systems and the DateTime model

The core mechanism visible in the README is an immutable value model. The example methods build new objects rather than modifying existing ones: fromDate.plusYears(1).withDayOfYear(1) produces a new LocalDate, and a Period is assembled through chained withDays and withHours calls. This is the main architectural difference from the pre-Java 8 JDK classes, where a Calendar could be mutated by any method that received a reference to it.

The API splits types by what they represent. DateTime carries a full instant plus a chronology and zone. LocalDate carries a date without a time. Days and Period express amounts of time, and daysBetween returns the interval between two dates as a typed object rather than a bare number. Formatting and parsing are handled by separate classes, and the README shows locale-aware text output through monthOfYear().getAsText(Locale.ENGLISH).

Pluggable chronologies are the feature that has no direct equivalent in the standard library. The README lists the Buddhist, Coptic, Ethiopic and Islamic systems alongside Gregorian and Julian. For an application that must display or compute dates in one of those calendars, that support is the reason to choose this library over a hand-rolled conversion. The trade-off is conceptual weight: DateTime, LocalDate, Instant, Period, Duration and Interval each mean something distinct, and picking the wrong one produces code that compiles but reads badly. The quick and full user guides linked from the README are the place to sort that out before writing production code.

Adding the Joda-Time Maven dependency and parsing a date

The README points to the installation page for download and installation details, and states that release 2.14.4 is available in Maven Central. It gives the Maven coordinates directly. The version element is the one piece you should re-check against Maven Central before committing, because a copied snippet ages faster than the library does.

<dependency>
  <groupId>joda-time</groupId>
  <artifactId>joda-time</artifactId>
  <version>2.14.4</version>
</dependency>

Gradle users get the equivalent one-liner from the README. Note that it uses the older compile configuration.

compile 'joda-time:joda-time:2.14.4'

With the dependency resolved, the README's own example is a reasonable first exercise. It shows a date built from a year, month and day, then a typed interval computed against the first day of the following year.

public Days daysToNewYear(LocalDate fromDate) {
  LocalDate newYear = fromDate.plusYears(1).withDayOfYear(1);
  return Days.daysBetween(fromDate, newYear);
}

Call it with a LocalDate for today and you get a Days object holding the number of whole days to 1 January of the next year. Two things are worth noticing on the first run. The original fromDate is unchanged, because plusYears returns a new instance. And the result is a Days, not an int, so printing it directly shows a typed value rather than a plain number. If your build targets a JDK older than 8, confirm that the compiler level matches the library's stated JDK 1.5 or later requirement before chasing build errors elsewhere.

Where Joda-Time is the wrong choice

The README answers this one itself, and the answer is blunt. From Java SE 8 onwards, users are asked to migrate to java.time, the JSR-310 API that is part of the JDK and replaces this project. On Android, java.time is available from API 26 and above. For projects that must support lower API levels, the README points to the ThreeTenABP library instead.

The practical consequence is that a new Java SE 8 or later project adding Joda-Time takes on a dependency for functionality the JDK already provides. That dependency then needs version tracking, security review and upgrade handling for as long as the application lives, in exchange for very little, since the README states no major enhancements are planned.

A second limitation is cultural rather than technical. Support runs through Stack Overflow for usage questions, with GitHub issues and pull requests reserved for people who want to advance the project. A team expecting a vendor-style support channel will not find one here, though the README notes that Joda-Time is available as part of the Tidelift Subscription for organisations that want a commercial arrangement.

Finally, be careful with the word deprecated. The README does not say Joda-Time is deprecated. It says it is no longer in active development except for timezone data, and that Java SE 8 and later users are asked to migrate. Those are different claims, and the distinction matters if you are justifying an existing dependency to a reviewer: the library is maintained, but it is not growing.

How java.time and ThreeTenABP differ in approach

The real alternative for most readers is java.time, and the difference is not just packaging. java.time is part of the JDK, so it adds no dependency, no version to track and no licence file to carry. Its API was designed after Joda-Time and by much of the same thinking, so the concepts transfer: an immutable local date type, a separate instant type, and explicit durations and periods. Migration is mostly mechanical for straightforward date arithmetic, which is why the README can ask users to move without further qualification.

The gap is calendar coverage. Joda-Time ships Buddhist, Coptic, Ethiopic and Islamic chronologies as first-class options. If your application computes dates in one of those systems, java.time does not remove the need for a library, and the README's migration advice assumes you are not in that group. That is the clearest case where the standard library is not a drop-in answer.

ThreeTenABP is the alternative with a different constraint rather than a different design. It exists for Android projects that cannot reach API 26, and it brings the java.time API to lower API levels. Choosing it over Joda-Time means writing code against the API you would use on a modern device, which makes a later minimum-SDK bump a non-event. Choosing Joda-Time means committing to an API that the ecosystem is moving away from. For a new Android module, that difference is worth more than any single feature.

Licence, upgrade cost and what maintenance means here

Joda-Time is licensed under Apache 2.0, which the README calls a business-friendly licence. The repository carries LICENSE.txt and NOTICE.txt at the top level, so the attribution files are present and can be redistributed with a binary. Apache 2.0 also includes a patent grant, which is often the reason a legal review prefers it over a bare permissive licence. None of this is legal advice; check your own obligations, particularly around the NOTICE file if you repackage the jar.

The upgrade cost is low by design. The 2.x line is declared stable and worthy of the 2.x tag, and the 2026 releases are patch-level. Timezone data updates are the reason to keep moving forward on that line, since stale timezone rules produce wrong offsets for regions that have changed their rules. There is no migration guide to read for a 2.14.x bump, and the README documents no breaking changes at that level.

The cost that does not go away is the migration you are deferring. Every year a codebase stays on Joda-Time is a year of calls written against an API the README itself asks Java SE 8 users to leave. For a project pinned to an old JDK, that is a fixed cost you have already accepted. For a project that could move, it is a decision to keep paying. The release process described in the README is manual and tag-driven, with GitHub Actions building the code and website, so releases depend on maintainer attention rather than an automated pipeline.

Editorial conclusion

Adopt Joda-Time when you maintain a pre-Java 8 codebase, or an Android app below API 26, and you need multiple calendar systems or a date API that does not mutate its objects. Do not adopt it for new Java SE 8 or later projects: the README asks those users to migrate to java.time, and no major enhancements are planned. Before committing, verify your JDK target against the stated JDK 1.5 or later requirement, confirm the exact version in Maven Central rather than trusting a copied snippet, and check whether the classes you need already exist in java.time, because the migration cost is lowest before you write the first call.

Frequently asked questions

Official sources

1. JodaOrg/joda-time on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases