Apache POI for Java: Complete Guide with Examples

1. What is Apache POI and why is it needed?

Apache POI (Poor Obfuscation Implementation) is a powerful open-source library in the Java language, designed for creating, reading, and modifying Microsoft Office format files (Excel, Word, PowerPoint, Outlook). It allows developers to programmatically manage documents without needing to install the Microsoft Office suite itself. The library provides two main APIs: HSSF (Horrible Spreadsheet Format) for working with .xls format files (Excel 97-2003) and XSSF (XML Spreadsheet Format) for working with the modern .xlsx format (Excel 2007+). For Word files, similar components are used: HWPF (for .doc) and XWPF (for .docx).

Why is this needed? In modern development, there is often a need to automate work with office documents: generate reports, import data from spreadsheets, create contract templates, or compile complex analytical summaries. Apache POI solves these tasks by giving Java developers full control over the document structure: from cell formatting and creating charts in Excel to working with tables, images, and styles in Word.

The library is actively maintained by the Apache Software Foundation community, has extensive documentation, and is used in large enterprise projects. It is compatible with Java 8 and above, making it a universal tool for most modern Java applications, including web services, desktop applications, and data processing systems.

2. Installation

Apache POI is distributed via the Maven Central Repository. To add it to a project, you need to include dependencies in the pom.xml file (for Maven) or build.gradle file (for Gradle).

Maven

<!-- Main dependency for working with Excel (.xls and .xlsx) -->\n<dependency>\n    <groupId>org.apache.poi</groupId>\n    <artifactId>poi-ooxml</artifactId>\n    <version>5.3.0</version>\n</dependency>\n\n<!-- For working with Word documents (.doc and .docx) -->\n<dependency>\n    <groupId>org.apache.poi</groupId>\n    <artifactId>poi-scratchpad</artifactId>\n    <version>5.3.0</version>\n</dependency>

Gradle

implementation 'org.apache.poi:poi-ooxml:5.3.0'\nimplementation 'org.apache.poi:poi-scratchpad:5.3.0'

Important: Version 5.3.0 is current as of the time of writing this article. It is recommended to check the latest version on Maven Repository. Also note that poi-ooxml already includes poi (the base module) and poi-ooxml-lite (for working with OOXML formats).

3. Quick Start: Minimal Working Example

Let's create a simple Excel file with one row of data and write it to disk.

import org.apache.poi.ss.usermodel.*;\nimport org.apache.poi.xssf.usermodel.XSSFWorkbook;\n\nimport java.io.FileOutputStream;\nimport java.io.IOException;\n\npublic class QuickStart {\n    public static void main(String[] args) {\n        // Create a new workbook for the .xlsx format\n        try (Workbook workbook = new XSSFWorkbook()) {\n            // Create a sheet named "Data"\n            Sheet sheet = workbook.createSheet("Data");\n\n            // Create a row (index 0 — first row)\n            Row row = sheet.createRow(0);\n\n            // Create a cell in column A (index 0)\n            Cell cell = row.createCell(0);\n            cell.setCellValue("Hello, Apache POI!");\n\n            // Create a cell in column B (index 1) with a numeric