Setup & Installation

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

Baseline date: 2026-10-12. This page was written against Apache Tika 4.1.0 (the latest release on Maven Central on that date) and Tika 3.3.2 (the latest 3.x release), Java 21 and later for the examples (Tika 4.x itself needs Java 17, Tika 3.x needs Java 11), Spring Boot 4.x on Spring Framework 7 and the Docker image apache/tika:4.1.0. It shows how to get Tika into a build, how to run the zip distributions and the container, and how to avoid the two classic installation problems: a jar that fails with NoClassDefFoundError and a dependency tree that carries a second copy of POI or PDFBox. The architecture behind the artifact names is in Introduction & Architecture.

Requirements

  • Java. Tika 4.x requires Java 17 or later; the download page states it explicitly. Tika 3.x runs on Java 11 or later. The examples in this section are written for Java 17 language level and run on Java 21 or later.

  • A build tool that can resolve Maven Central (Maven or Gradle), or the zip distributions and Docker for the command line and the server.

  • No native tools for the standard parsers. Everything in tika-parsers-standard-package is pure Java. Optional features shell out to external programs (Tesseract for OCR, ImageMagick, ffmpeg, GDAL); the -full Docker image includes them.

Maven

The simplest dependency set

tika-parsers-standard-package is a pom-packaged artifact that pulls in tika-core and every standard parser module. Maven needs <type>pom</type> to treat it as a dependency aggregator.

<dependencies>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-core</artifactId>
        <version>4.1.0</version>
    </dependency>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-parsers-standard-package</artifactId>
        <version>4.1.0</version>
        <type>pom</type>
    </dependency>
</dependencies>

Source: Using Tika as a Library (Java API), Dependencies.

Forgetting <type>pom</type> makes Maven look for a jar that does not exist and fail with a "could not find artifact …​:jar" error.

The bill of materials

tika-bom is published at 4.1.0 and keeps all Tika artifacts at one version, so only the BOM carries the number. This setup was resolved and checked with mvn dependency:tree on 2026-10-12:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.tika</groupId>
            <artifactId>tika-bom</artifactId>
            <version>4.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-parsers-standard-package</artifactId>
        <type>pom</type>
    </dependency>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-serialization</artifactId>
    </dependency>
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-pipes-fork-parser</artifactId>
    </dependency>
</dependencies>

Spring Boot’s dependency management does not include Tika, so a Boot project declares the Tika version itself, either through this BOM or a tika.version property.

Source: tika-bom on Maven Central.

Choosing artifacts

Artifact (org.apache.tika) Adds Needed for

tika-core

Detection by magic and name, Parser and Detector APIs, Metadata, TikaInputStream, the Tika facade

Always

tika-parsers-standard-package (pom)

All standard format parsers and the encoding detectors

Reading real documents

tika-parser-pdf-module, tika-parser-microsoft-module, tika-parser-html-module, tika-parser-text-module, tika-parser-mail-module, tika-parser-pkg-module, tika-parser-xml-module, and others

One format family each

Replacing the package with only the parsers the application needs, for a smaller classpath

tika-serialization

JSON serialization, TikaLoader and tika-config.json loading

Configuration in 4.x

tika-pipes-fork-parser

PipesForkParser, which parses in a separate JVM; brings the pipes core, the file-system fetcher and a Log4j 2 logging stack

Embedding Tika with process isolation

tika-langdetect-*

Language detectors (tika-langdetect-charsoup is pulled in by the pipes and eval modules)

Language detection pages

tika-parsers-extended, tika-parsers-ml modules, shaded tika-parser-*-package jars

Scientific formats, SQLite, NLP, inference and VLM parsers

Optional, specialised parsing

The standard package also adds the encoding-detector modules (tika-encoding-detector-html, tika-encoding-detector-mojibuster and tika-ml-junkdetect). When you select modules by hand, check text and HTML charset detection with a legacy-encoded file such as legacy-catalogue.txt before shipping, because a missing detector changes the result silently.

What the standard package brings

The table lists the main third-party libraries in the resolved tree of the setup above (Tika 4.1.0), as checked on 2026-10-12. It matters when your application uses the same libraries at a different version.

Library Resolved version Used for

Apache POI (poi, poi-ooxml, poi-scratchpad)

5.5.1

Word, Excel, PowerPoint and Visio

Apache PDFBox (pdfbox, fontbox, pdfbox-tools)

3.0.8

PDF

Apache Commons Compress

1.28.0

Archives (ZIP, TAR, 7z and others)

Apache Commons IO

2.22.0

I/O helpers

jsoup

1.23.2

HTML

Apache James Mime4j

0.8.15

E-mail (EML)

Jackson (jackson-databind and friends)

2.22.x

JSON configuration and serialization

Bouncy Castle (bcprov, bcpkix)

1.86

Encrypted PDF and signed content

XMLBeans

5.4.1

OOXML schemas used by POI

SLF4J API

2.0.20

Logging facade

Versions move with every Tika release; re-run mvn dependency:tree after an upgrade instead of trusting this table.

Gradle

Gradle resolves the POM of tika-parsers-standard-package as module metadata, so the dependencies are pulled in without a special type. Use the BOM as a platform:

dependencies {
    implementation(platform("org.apache.tika:tika-bom:4.1.0"))
    implementation("org.apache.tika:tika-core")
    implementation("org.apache.tika:tika-parsers-standard-package")
    implementation("org.apache.tika:tika-serialization")
    implementation("org.apache.tika:tika-pipes-fork-parser")
}

This Gradle snippet was written from the Gradle platform semantics and the verified Maven resolution above and was not run for this page; run ./gradlew dependencies once to confirm the resolved versions.

Source: Gradle, Sharing dependency versions between projects.

The zip distributions

In 4.x, tika-app, tika-server-standard and tika-eval-app are thin launchers, not fat jars. The same jars are published on Maven Central for dependency resolution, but running one alone fails. Download the matching zip, unpack it and run the jar from inside the directory, where lib/ (and plugins/) sit next to it. The zip has no top-level directory of its own, so unpack it into a new directory.

unzip tika-app-4.1.0.zip -d tika-app-4.1.0
cd tika-app-4.1.0
java -jar tika-app-4.1.0.jar --help

Running the bare jar fails with the NoClassDefFoundError described in the official FAQ. The fix is never a bigger classpath: use the zip. The same layout applies to tika-server-standard-4.1.0.zip, which also includes service install scripts. Optional Tika Pipes plugins (file system, S3, Solr, Elasticsearch, Kafka and more) are separate zips that you unpack into the plugins/ directory of the app or server distribution.

The 3.x line is different: tika-app-3.3.2.jar and tika-server-standard-3.3.2.jar are runnable jars, and the server also ships as -bin.zip and -bin.tgz for service installs.

Verify downloads with the PGP signatures and SHA512 sums linked from the download page; take the KEYS file from the main distribution site, not from a mirror.

Source: Apache Tika, Download and FAQ, "java -jar tika-app.jar fails with NoClassDefFoundError".

Docker quick start

The project publishes apache/tika (REST server, port 9998) and apache/tika-grpc (gRPC server, port 9090). The minimal image contains a JRE and the tika-server-standard distribution with every pure-Java parser; the -full image adds Tesseract with several language packs, GDAL, ImageMagick, ffmpeg and fonts.

docker run -d -p 127.0.0.1:9998:9998 apache/tika:4.1.0
curl -T manuscript.docx -H "Accept: text/plain" http://localhost:9998/tika

Bind to 127.0.0.1 unless you mean to publish the port: Docker writes its own firewall rules, so a plain -p 9998:9998 can expose the server to the internet past the host firewall, and Tika parses untrusted input by design. The command above comes from the official documentation and was not run for this page; the Tika Server (REST API) and Docker & Kubernetes Deployment pages show the real endpoint output.

Tag Meaning

4.1.0

Minimal image; rolls forward if the image is rebuilt for the same release.

4.1.0-1

Immutable build number of the same image; pin this form in production.

4.1.0-full, 4.1.0-1-full

With the external tools for OCR, imaging and media.

latest, latest-full

Newest stable release.

Source: Running Tika in Docker and apache/tika on Docker Hub. A full treatment of the container, memory settings and Kubernetes is on the Docker & Kubernetes Deployment page of this section; the general Docker background is in Getting Started with Docker.

Logging

Tika logs through the SLF4J 2.x API (slf4j-api 2.0.20 in the resolved tree) and the standard package adds jcl-over-slf4j, which routes Commons Logging calls from libraries to SLF4J. You have to provide a binding, or SLF4J prints a warning that no provider was found and discards the messages. Which binding depends on the application:

  • Spring Boot: Logback is already the binding; add nothing, and see Logging in Spring Boot. Remove any log4j-slf4j2-impl that a transitive dependency brings, because two bindings at once give a warning and an arbitrary choice. tika-pipes-fork-parser is such a dependency (see the next bullet), so exclude its Log4j 2 binding and core in a Boot project:

    <dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-pipes-fork-parser</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-slf4j2-impl</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

    With Gradle, use exclude(group = "org.apache.logging.log4j", module = "log4j-slf4j2-impl") (and the same for log4j-core) on that dependency. The exclusion was not run for this page; check mvn dependency:tree afterwards.

  • Plain Java with Log4j 2: add org.apache.logging.log4j:log4j-slf4j2-impl and log4j-core and a log4j2.xml. tika-pipes-fork-parser already brings log4j-core, log4j-api and log4j-slf4j2-impl (2.26.1 in the resolved tree), so the logging binding comes with the forked parser and its INFO lines appear on the console.

  • Apache POI logs through the Log4j 2 API, not SLF4J; use log4j-to-slf4j when your application logs with Logback. See Setup & Dependencies in the Office Files section.

The forked JVM of PipesForkParser writes its own log lines, prefixed with the client id, to the console of the parent. Redirecting or silencing them is covered on the Robustness, Limits & Timeouts and Tika Pipes pages.

Source: SLF4J user manual and Log4j 2 API.

Dependency clashes with POI and PDFBox

Tika’s Microsoft and PDF modules bring Apache POI 5.5.1 and Apache PDFBox 3.0.8 in the 4.1.0 resolved tree. Applications often use the same libraries directly (the Office Files and PDF Generation sections of this site, for instance), and two versions on one classpath is the classic way to get NoSuchMethodError or NoClassDefFoundError at runtime.

  • Check first. Run mvn dependency:tree -Dincludes=org.apache.poi,org.apache.pdfbox and compare the versions with the ones your code compiles against.

  • Let one version win. Maven resolves a transitive conflict by "nearest definition". Declare the POI and PDFBox artifacts you want in your own dependencyManagement and keep them at the version Tika was tested with when you can. A newer minor of the same major line usually works; a different major (PDFBox 2.x with Tika 4) does not.

  • Keep the POI family at one version, as described in Setup & Dependencies: mixing poi 5.5.1 with poi-ooxml from a different release is unsupported.

  • Use isolation. Running Tika in a service (the Docker image or PipesForkParser) keeps Tika’s copy of these libraries out of your classpath altogether, which is the cleanest solution to a persistent clash.

  • Beware of Jackson and Commons IO. Tika brings Jackson 2.22.x and Commons IO 2.22.0; a framework that manages other versions of them (Spring Boot manages many) can silently replace Tika’s. Check the effective tree after adding Tika.

  • Tika 3.3.0 and later moved to poi-ooxml-full in the 3.x line (see the 3.x column below); 4.1.0’s tree shows poi-ooxml. Do not add both.

Tika 3.x or 4.x

Aspect 3.x (3.3.2) 4.x (4.1.0)

Java

11 or later

17 or later

Support

Maintenance line: bug fixes and dependency upgrades. End of support: March 2027 according to the 4.1.x roadmap page; "January 2027 or 6 months after 4.0.0, whichever comes first" according to the wiki roadmap. Check both before planning a migration.

Active development

Configuration

tika-config.xml and TikaConfig

JSON tika-config.json and TikaLoader; TikaConfig removed

Parser and detector API

InputStream

TikaInputStream

Default output of app, server and pipes

XHTML

Markdown (ask for XHTML explicitly)

Metadata keys

X-TIKA: prefix, resourceName

tk: prefix, kebab-case

Command line and server

Runnable jars

Zip distributions with lib/ and plugins/

Docker images

apache/tika 3.x tags

apache/tika:4.1.0, -full, plus apache/tika-grpc

Notable 3.3.x changes

3.3.0 moved to poi-ooxml-full; 3.3.2 made the SAX-based OOXML parsers the default and requires enableUnsecureFeatures=true for /pipes, /async and /status

Choose 4.x for new projects. Stay on 3.x only while a dependency or the Java version forces it, and plan the move before its end of support; the What’s Changed & Migration page of this section lists what changes. The official migration guide is the primary reference.

Source: Migrating to Tika 4.x, Roadmap and Download.

Verify the installation

A short program that touches detection, a parser and a version check proves that the classpath is complete. It uses manuscript.docx from the Bookshelf scenario and was run against Tika 4.1.0.

import java.io.IOException;
import java.nio.file.Path;
import org.apache.tika.Tika;
import org.apache.tika.exception.TikaException;

public class InstallCheck {

    public static void main(String[] args) throws IOException, TikaException {
        Tika tika = new Tika();
        Path file = Path.of("manuscript.docx");

        System.out.println("type: " + tika.detect(file));
        System.out.println("text: " + tika.parseToString(file).strip());
    }
}

Output:

type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
text: The Lighthouse Keeper
Chapter one begins at dusk.

If detect returns application/zip or application/x-tika-ooxml for a Word file, the Microsoft parser module is missing from the classpath. If parseToString returns an empty string for a PDF, check that tika-parser-pdf-module is present and that the PDF is not a scan.

Source: Tika facade, Javadoc 4.1.0.

Checklist

  • Java 17 or later for Tika 4.x.

  • tika-core plus tika-parsers-standard-package with <type>pom</type>; import tika-bom to keep versions together.

  • Add tika-serialization for JSON configuration and tika-pipes-fork-parser for isolated parsing.

  • Unpack the app and server zips and run from inside the directory; never run the bare jar.

  • In Docker bind to 127.0.0.1, pin <version>-<N> tags and use the -full image only if you need OCR or media tools.

  • Provide one SLF4J binding.

  • Check POI, PDFBox, Jackson and Commons IO with dependency:tree.

References