Versioning and maintenance policy

Versioning policy

Since version 2.0, Log4j follows semantic versioning, with release numbers of the form:

<major>.<minor>.<patch>[-<pre-release>]

where:

<major>

The major version number is incremented when breaking changes are introduced.

Upgrading to a new major version typically requires code changes in your application. For each major release, a migration guide is provided.

See Migrating from Log4j 1 for instructions on migrating from Log4j 1 to Log4j 2.

<minor>

The minor version number is incremented when new features are added in a backward-compatible manner, such as:

  • New Java methods or classes added to the public API of one of the Log4j artifacts.

  • New configuration attributes added to Log4j Plugins (appenders, layouts, filters, etc.).

  • Functionality or Java methods/classes being deprecated.

  • Behavioral changes introduced without breaking the public API.

Upgrading to a new minor version usually does not require code changes, unless you rely on undocumented behavior that has changed. To avoid accumulating such changes, we recommend upgrading minor versions regularly.

When upgrading to a new minor version, review the corresponding Release notes, where behavioral changes are highlighted.

<patch>

The patch version number is incremented when only backward-compatible bug fixes are introduced.

Upgrading to a new patch release is the simplest upgrade path.

Click to see the OSGi package versioning policy

Since release 2.21.0, Log4j follows OSGi best practices by versioning each Java package individually (see Versioning Packages for details). Package versions are available in the manifest of each artifact and in the package Javadoc. For example, the version of the org.apache.logging.log4j.core.appender package appears in the package summary page.

Package versions have the form X.Y.Z, where the X.Y portion corresponds to the Log4j version that last introduced changes to the package’s public API. For example, if a package has version 2.34.5, then all functionality in that package has been available since Log4j 2.34.0.

Version alignment

Because Log4j API and Log4j Core implementation are separate artifacts, their versions at runtime must be aligned:

  • Log4j Core version X depends on Log4j API version X, so you must have at least version X of Log4j API at runtime.

  • Conversely, to use all methods provided by Log4j API version X, you need a Log4j Core version that implements them, i.e., Log4j Core version X or later.

The easiest way to ensure version alignment in your project is to use the log4j-bom artifact in your build tool. Using log4j-bom guarantees that compatible versions are selected, regardless of your tool’s dependency resolution strategy.

Version lifecycle and maintenance policy

Minor releases of Log4j follow a defined lifecycle consisting of four phases:

Active development (AD)

The version is under active development and may introduce new features. Pre-release builds (alpha, beta, etc.) may be published during this phase; vulnerability reports are accepted and will be addressed.

Versions in this phase are not recommended for production use.

Active maintenance (AM)

The version is considered stable and suitable for production. In this phase, no new features are accepted: only bug fixes and security fixes. Vulnerability reports are accepted and will be addressed.

Due to the limited resources of the Log4j project, only the latest minor release of the latest major version remains in Active Maintenance.

End-of-maintenance (EOM)

The version is no longer actively maintained. New releases, including security fixes, are very unlikely. Vulnerability reports may still be submitted, but fixes will be produced only in exceptional circumstances.

Because the project is volunteer-driven, any PMC member may choose to create a release for an EOM version, but such releases should be considered exceptional.

End-of-life (EOL)

The version is no longer maintained, and vulnerability reports are not accepted.

This final phase is entered after an official PMC vote and public announcement.

We avoid using the term support to describe the maintenance phases, because support remains available in all phases:

  • See Community support for the community-run discussion channels that are offered on a best-effort basis.

  • Although the ASF does not endorse any third-party commercial providers, some companies may offer paid support for EOM or EOL versions. See Commercial support for a publicly maintained list of such providers.