Installation

In this page we will elaborate on various ways to install Log4j in your library or application.

Shortcuts

Below we share some shortcuts for the impatient.

We strongly advise you to skim through this page to get a grip on fundamental logging concepts and understand which recipe fits your bill best.
Are you a library developer?

You just need to log against a logging API. See Installing Log4j API.

Are you an application developer?

Your code and libraries it depends on are most probably already logging against a logging API, you just need to install a logging implementation. See Installing Log4j Core.

Are you a Spring Boot application developer?

See Installing Log4j Core for Spring Boot applications.

Are you migrating from…​

Log4j 1, Logback, or SLF4J?

Concepts (APIs, Implementations, and Bridges)

It is crucial to understand certain concepts in logging to be able to talk about the installation of them.

Logging API

A logging API is an interface your code or your dependencies directly logs against. It is required at compile-time. It is implementation agnostic to ensure that your application can write logs, but is not tied to a specific logging implementation. Log4j API, SLF4J, JUL (Java Logging), JCL (Apache Commons Logging), JPL (Java Platform Logging) and JBoss Logging are major logging APIs.

Logging implementation

A logging implementation is only required at runtime and can be changed without the need to recompile your software. Log4j Core, JUL (Java Logging), Logback are the most well-known logging implementations.

Logging bridge

Logging implementations accept input from a single logging API of their preference; Log4j Core from Log4j API, Logback from SLF4J, etc. A logging bridge is a simple logging implementation of a logging API that forwards all messages to a foreign logging API. Logging bridges allow a logging implementation to accept input from other logging APIs that are not their primary logging API. For instance, log4j-slf4j2-impl bridges SLF4J calls to Log4 API and effectively enables Log4j Core to accept input from SLF4J.

With this in mind, the type of software you are writing determines whether you should be installing a logging API, implementation, or bridge:

Libraries

They only require a logging API and delegate the choice of the implementation to applications. If a logging implementation is required by tests of the library, it should be in the appropriate test scope.

Applications

They need a logging implementation, but also bridges of each of the major logging APIs to support log statements from the libraries they use. For example, your application might be logging against Log4j API and one of its dependencies against SLF4J. In this case, you need to install log4j-core and log4j-slf4j2-impl.

To make things a little bit more tangible, consider the following visualization of a typical Log4j Core installation with bridges for an application:

Visualization of a typical Log4j Core installation with SLF4J, JUL, and JPL bridges
Figure 1. Visualization of a typical Log4j Core installation with SLF4J, JUL, and JPL bridges

Requirements

The Log4j 2 runtime requires a minimum of Java 8. See the Download page for older releases supporting Java 6 and 7.

Configuring the build tool

The easiest way to install Log4j is through a build tool such as Maven or Gradle. The rest of the instructions in this page assume you use one of these.

Importing the Bill-of-Materials (aka. BOM)

To keep your Log4j module versions in sync with each other, a BOM (Bill of Material) file is provided for your convenience. You can import the BOM in your build tool of preference:

  • Maven

  • Gradle

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-bom</artifactId>
      <version>2.24.1</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>
dependencies {
  implementation platform('org.apache.logging.log4j:log4j-bom:2.24.1')
}

Once you import the BOM, you don’t need to explicitly provide the versions of the Log4j artifacts managed by it.

In the rest of the explanations, we will assume that the Log4j BOM is imported.

Using snapshots

Do you want to test the latest (unstable!) development version? Click here details.

You can access the latest development snapshots by using the https://repository.apache.org/content/groups/snapshots/ repository.

Snapshots are published for development and testing purposes; they should not be used at production!

  • Maven

  • Gradle

<repositories>
  <repository>
    <id>apache.snapshots</id>
    <name>Apache Snapshot Repository</name>
    <url>https://repository.apache.org/snapshots</url>
    <releases>
      <enabled>false</enabled>
    </releases>
  </repository>
</repositories>
repositories {
  mavenCentral()
  maven { url 'https://repository.apache.org/snapshots' }
}

Installing Log4j API

The easiest way to install Log4j API is through a dependency management tool such as Maven or Gradle, by adding the following dependency:

  • Maven

  • Gradle

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-api</artifactId>
  <version>${log4j-api.version}</version>
</dependency>
implementation 'org.apache.logging.log4j:log4j-api:${log4j-api.version}'

Installing a logging implementation

Log4j provides several modules to facilitate the deployment of different logging implementations:

log4j-core

The reference implementation. Log4 Core primarily accepts input from Log4j API. Refer to Installing Log4j Core for the installation instructions.

log4j-to-jul

The bridge that translates Log4j API calls to JUL (Java Logging). See Installing JUL for the installation instructions.

log4j-to-slf4j

The bridge that translates Log4j API calls to SLF4J. Since currently only Logback implements SLF4J natively, refer to Installing Logback for the installation instructions.

To ensure that your code does not directly depend on a particular logging implementation, the logging backend should be put in the appropriate scope of your dependency manager:

Software type

Build tool

Maven

Gradle

Application

runtime

runtimeOnly

Library

test

testRuntimeOnly

Installing Log4j Core

Log4j Core is the reference logging implementation of the Log4j project. It primarily accepts input from Log4j API.

Do you have a Spring Boot application? You can directly skip to Installing Log4j Core for Spring Boot applications.

To install Log4j Core as your logging implementation, you need to add the following dependency to your application:

  • Maven

  • Gradle

<dependencies>

  <!-- Logging implementation (Log4j Core) -->
  <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
      <scope>runtime</scope>
  </dependency>

  <!-- Logging bridges will follow... -->

</dependencies>
runtimeOnly 'org.apache.logging.log4j:log4j-core'
// Logging bridges will follow...

Installing bridges

If either your application or one of its dependencies logs against a logging API that is different from Log4j API, you need to bridge that API to Log4j API.

Do you need bridges? And if so, which ones?

  • If you have any direct or transitive dependency on org.slf4j:slf4j-api, you need the SLF4J-to-Log4j bridge.

  • If you have any direct or transitive dependency on commons-logging:commons-logging, you need the JCL-to-Log4j bridge.

  • If it is a standalone application (i.e., not running in a Java EE container), you will probably need JUL-to-Log4j and JPL-to-Log4j bridges.

The following sections explain the installation of Log4j-provided bridges.

Installing SLF4J-to-Log4j bridge

You can translate SLF4J calls to Log4j API using the log4j-slf4j2-impl artifact:

  • Maven

  • Gradle

We assume you use log4j-bom for dependency management.

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j2-impl</artifactId>
  <scope>runtime</scope>
</dependency>

We assume you use log4j-bom for dependency management.

runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl'
Are you still using SLF4J 1.x?

Add this example instead:

  • Maven

  • Gradle

We assume you use log4j-bom for dependency management.

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j-impl</artifactId>
  <scope>runtime</scope>
</dependency>

We assume you use log4j-bom for dependency management.

runtimeOnly 'org.apache.logging.log4j:log4j-slf4j-impl'
Installing JUL-to-Log4j bridge

You can translate JUL (Java Logging) calls to Log4j API using the log4j-jul artifact:

  • Maven

  • Gradle

We assume you use log4j-bom for dependency management.

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-jul</artifactId>
  <scope>runtime</scope>
</dependency>

We assume you use log4j-bom for dependency management.

runtimeOnly 'org.apache.logging.log4j:log4j-jul'

In order to activate the bridge from JUL to Log4j API, you also need to add:

-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager

to the JVM parameters in your application launcher.

The JUL-to-Log4j bridge supports additional configuration and installation methods. See JUL-to-Log4j bridge for more information.

Installing JPL-to-Log4j bridge

You can translate JPL (Java Platform Logging) calls to Log4j API using the log4j-jpl artifact:

  • Maven

  • Gradle

We assume you use log4j-bom for dependency management.

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-jpl</artifactId>
  <scope>runtime</scope>
</dependency>

We assume you use log4j-bom for dependency management.

runtimeOnly 'org.apache.logging.log4j:log4j-jpl'
Installing JCL-to-Log4j bridge

Since version 1.3.0 Apache Commons Logging natively supports Log4j API.

You can enforce the version of a transitive dependency using the dependency management mechanism appropriate to your build tool:

  • Maven

  • Gradle

Maven users should add an entry to the <dependencyManagement> section of their POM file:

<dependencyManagement>
  <dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.3.4</version>
  </dependency>
</dependencyManagement>

Gradle users should refer to the Using a platform to control transitive versions of the Gradle documentation.

Are you using Commons Logging 1.2.0 or earlier?

You need to install the following dependency instead:

  • Maven

  • Gradle

We assume you use log4j-bom for dependency management.

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-jcl</artifactId>
  <scope>runtime</scope>
</dependency>

We assume you use log4j-bom for dependency management.

runtimeOnly 'org.apache.logging.log4j:log4j-jcl'
Installing JBoss Logging-to-Log4j bridge

JBoss Logging is shipped with an integrated bridge to Log4j API and requires no steps on your part. See Supported Log Managers for more information.

Installing Log4j Core for Spring Boot applications

Spring Boot users should replace the spring-boot-starter-logging dependency with spring-boot-starter-log4j2:

  • Maven

  • Gradle

<dependencies>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <exclusions>
      <exclusion>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-logging</artifactId>
      </exclusion>
    </exclusions>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
    <scope>runtime</scope>
  </dependency>

</dependencies>
configurations {
  all.exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
}

dependencies {
  runtimeOnly group: 'org.springframework.boot', module: 'spring-boot-starter-log4j2'
}

The spring-boot-starter-log4j2 artifact will automatically install Log4j Core, JUL-to-Log4j bridge, and configure them. You don’t need to add any other dependency or configure JUL anymore. See Spring Boot Logging documentation for further information.

Configuring Log4j Core

As with any other logging implementation, Log4j Core needs to be properly configured. Log4j Core supports many different configuration formats: JSON, XML, YAML, and Java properties. To configure Log4j Core, see Configuration file. A basic configuration can be obtained by adding one of these files to your application’s classpath:

  • log4j2.xml

  • log4j2.json

  • log4j2.yaml

  • log4j2.properties

<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="https://logging.apache.org/xml/ns"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="https://logging.apache.org/xml/ns
                                   https://logging.apache.org/xml/ns/log4j-config-2.xsd">

  <appenders>
    <Console name="CONSOLE">
      <PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/>(1)
    </Console>
  </appenders>

  <loggers>
    <root level="INFO">
      <AppenderRef ref="CONSOLE"/>
    </root>
  </loggers>

</Configuration>
{
  "Configuration": {
    "Appenders": {
      "Console": {
        "name": "CONSOLE",
        "PatternLayout": {
          "pattern": "%d [%t] %5p %c{1.} - %m%n" (1)
        }
      }
    },
    "Loggers": {
      "Root": {
        "level": "INFO",
        "AppenderRef": {
          "ref": "CONSOLE"
        }
      }
    }
  }
}
Configuration:
  Appenders:
    Console:
      name: CONSOLE
      PatternLayout:
        pattern: "%d [%t] %5p %c{1.} - %m%n" (1)
  Loggers:
    Root:
      level: INFO
      AppenderRef:
        ref: CONSOLE
appender.0.type = Console
appender.0.name = CONSOLE
appender.0.layout = PatternLayout (1)
appender.0.layout.pattern = %d [%t] %5p %c{1.} - %m%n
rootLogger.level = INFO
rootLogger.appenderRef.0.ref = CONSOLE
1 While Pattern Layout is a good first choice and preferable for tests, we recommend using a structured format such as JSON Template Layout for production deployments.

To use these formats, the following additional dependencies are required:

  • log4j2.xml

  • log4j2.json

  • log4j2.yaml

  • log4j2.properties

JPMS users need to add:

module foo.bar {
    requires java.xml;
}

to their module-info.java descriptor.

  • Maven

  • Gradle

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.0</version>
    <scope>runtime</scope>
</dependency>
runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:2.18.0'

  • Maven

  • Gradle

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-yaml</artifactId>
    <version>2.18.0</version>
    <scope>runtime</scope>
</dependency>
runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.0'

No dependency required.

Installing JUL

Are you using JBoss Log Manager as your JUL implementation? You can skip this section and use the log4j2-jboss-logmanager and slf4j-jboss-logmanager bridges from the JBoss Logging project instead.

Java Platform contains a very simple logging API and its implementation called JUL (Java Logging). Since it is embedded in the platform, it only requires the addition of bridges from Log4j API and SLF4J:

  • Maven

  • Gradle

<dependencies>

    <!-- Log4j-to-JUL bridge -->
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-to-jul</artifactId>
    <scope>runtime</scope>
  </dependency>

  <!-- SLF4J-to-JUL bridge -->
  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-jdk14</artifactId>
    <version>2.0.16</version>
    <scope>runtime</scope>
  </dependency>

  <!-- ... -->

</dependencies>
runtimeOnly 'org.apache.logging.log4j:log4j-to-jul' // Log4j-to-JUL bridge
runtimeOnly 'org.slf4j:slf4j-jdk14:2.0.16' // SLF4J-to-JUL bridge

See also:

Installing Logback

To install Logback as the logging implementation, you only need to add a Log4j-to-SLF4J bridge:

  • Maven

  • Gradle

<dependencies>

  <!-- Logging implementation (Logback) -->
  <dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>{logback-version}</version>
    <scope>runtime</scope>
  </dependency>

  <!-- Log4j-to-SLF4J bridge -->
  <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-to-slf4j</artifactId>
    <scope>runtime</scope>
  </dependency>

</dependencies>
runtimeOnly 'ch.qos.logback:logback-classic:1.5.5'
runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j' // Log4j-to-SLF4J bridge

To configure Logback, see Logback’s configuration documentation.