Apache POIの使い方｜Excelの読み込み・書き込み・書式・大量出力

Apache POI は、Java から Excel ファイル（.xlsx・.xls）を読み書きするライブラリです。 依存に poi-ooxml を1つ足し、読み込みは WorkbookFactory.create()、書き込みは new XSSFWorkbook() から始めます。

よく検索で見かけるサンプルの多くは「文字列を1セル読む・書く」だけで、実務で困る 数値が 12345.0 で読める、日付が 46305.0 になる、数式の結果が取れない、大量出力でメモリが足りない といった点に触れていません。この記事では、そうした点を含めて、そのまま使えるコード全文と一覧表を1ページにまとめました。

確認環境：Apache POI 5.5.1（2025年11月30日リリース）の公式ドキュメントと Javadoc、Java 21 で確認（確認日 2026年10月10日）。

早見表：やりたいこと別

依存関係

<!-- Maven -->
<dependency>
  <groupId>org.apache.poi</groupId>
  <artifactId>poi-ooxml</artifactId>
  <version>5.5.1</version>
</dependency>

// Gradle
implementation 'org.apache.poi:poi-ooxml:5.5.1'

クラスの対応

インターフェース（Workbook・Sheet・Row・Cell）で書いておくと、.xls と .xlsx の両方で同じコードが動きます。

Excel を読み込む（コード全文）

社員一覧（社員番号・氏名・入社日・給与・賞与込みの年収＝数式）を読み込み、表示どおりの文字列と、型に合わせた値の両方を取り出します。

import java.io.File;
import java.time.LocalDateTime;
import java.util.Locale;

import org.apache.poi.ss.usermodel.Cell;
import org.apache.poi.ss.usermodel.CellType;
import org.apache.poi.ss.usermodel.DataFormatter;
import org.apache.poi.ss.usermodel.DateUtil;
import org.apache.poi.ss.usermodel.FormulaEvaluator;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.ss.usermodel.WorkbookFactory;

public class ReadExcel {

    public static void main(String[] args) throws Exception {
        try (Workbook wb = WorkbookFactory.create(new File("employees.xlsx"))) {   // xls も可
            Sheet sheet = wb.getSheetAt(0);
            FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator();
            DataFormatter formatter = new DataFormatter(Locale.JAPAN);

            for (Row row : sheet) {                       // 中身のある行だけが回る
                if (row.getRowNum() == 0) continue;       // 見出し行を飛ばす
                String id   = formatter.formatCellValue(row.getCell(0), evaluator);
                String name = formatter.formatCellValue(row.getCell(1), evaluator);
                Object hired = value(row.getCell(2), evaluator);
                Object total = value(row.getCell(4), evaluator);
                System.out.printf("%s %s %s %s%n", id, name, hired, total);
            }
        }
    }

    /** セルの種類に合わせて Java の値に変換する（空なら null） */
    static Object value(Cell cell, FormulaEvaluator evaluator) {
        if (cell == null) return null;
        CellType type = cell.getCellType();
        if (type == CellType.FORMULA) {
            type = evaluator.evaluateFormulaCell(cell);   // 数式を計算して結果の種類を得る
        }
        return switch (type) {
            case STRING  -> cell.getStringCellValue();
            case BOOLEAN -> cell.getBooleanCellValue();
            case NUMERIC -> DateUtil.isCellDateFormatted(cell)
                    ? cell.getLocalDateTimeCellValue().toLocalDate()   // 日付
                    : toNumber(cell.getNumericCellValue());            // 数値
            case BLANK   -> null;
            case ERROR   -> "#ERR" + cell.getErrorCellValue();
            default      -> null;
        };
    }

    /** 12345.0 を 12345 に（小数があればそのまま） */
    static Number toNumber(double d) {
        return (d == Math.rint(d) && Math.abs(d) < Long.MAX_VALUE) ? (Number) (long) d : d;
    }
}

読み込みのポイント

DataFormatter は「Excel の画面に表示されている文字列」を返すので、CSV に変換するときや、文字列として取り込むときに向いています。合計や比較に使う値は value() のように型で取り出します。

Excel を書き込む（書式つきのコード全文）

見出しの太字・背景色・罫線、日付と金額の表示形式、合計の数式、列幅、ウィンドウ枠の固定、オートフィルターまで設定します。

import java.io.FileOutputStream;
import java.time.LocalDate;
import java.util.List;

import org.apache.poi.ss.usermodel.BorderStyle;
import org.apache.poi.ss.usermodel.Cell;
import org.apache.poi.ss.usermodel.CellStyle;
import org.apache.poi.ss.usermodel.DataFormat;
import org.apache.poi.ss.usermodel.FillPatternType;
import org.apache.poi.ss.usermodel.Font;
import org.apache.poi.ss.usermodel.HorizontalAlignment;
import org.apache.poi.ss.usermodel.IndexedColors;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.ss.util.CellRangeAddress;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

public class WriteExcel {

    record Employee(String id, String name, LocalDate hired, int salary) {}

    public static void main(String[] args) throws Exception {
        List<Employee> list = List.of(
            new Employee("00123", "佐藤 花子", LocalDate.of(2024, 4, 1), 280_000),
            new Employee("00124", "鈴木 一郎", LocalDate.of(2025, 10, 1), 300_000),
            new Employee("00125", "高橋 健",   LocalDate.of(2026, 4, 1), 253_000));

        try (Workbook wb = new XSSFWorkbook();
             FileOutputStream out = new FileOutputStream("employees.xlsx")) {

            Sheet sheet = wb.createSheet("社員");

            // 書式はセルごとに作らず、最初に1回だけ作って使い回す
            DataFormat fmt = wb.createDataFormat();
            Font bold = wb.createFont();
            bold.setBold(true);

            CellStyle head = wb.createCellStyle();
            head.setFont(bold);
            head.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex());
            head.setFillPattern(FillPatternType.SOLID_FOREGROUND);
            head.setAlignment(HorizontalAlignment.CENTER);
            border(head);

            CellStyle text = wb.createCellStyle();
            text.setDataFormat(fmt.getFormat("@"));            // 文字列（0埋めを保つ）
            border(text);
            CellStyle date = wb.createCellStyle();
            date.setDataFormat(fmt.getFormat("yyyy/mm/dd"));
            border(date);
            CellStyle yen = wb.createCellStyle();
            yen.setDataFormat(fmt.getFormat("#,##0"));
            border(yen);

            String[] titles = {"社員番号", "氏名", "入社日", "月給", "年収（16か月分）"};
            Row header = sheet.createRow(0);
            for (int i = 0; i < titles.length; i++) {
                Cell c = header.createCell(i);
                c.setCellValue(titles[i]);
                c.setCellStyle(head);
            }

            int r = 1;
            for (Employee e : list) {
                Row row = sheet.createRow(r);
                cell(row, 0, text).setCellValue(e.id());
                cell(row, 1, text).setCellValue(e.name());
                cell(row, 2, date).setCellValue(e.hired());     // LocalDate をそのまま渡せる
                cell(row, 3, yen).setCellValue(e.salary());
                cell(row, 4, yen).setCellFormula("D" + (r + 1) + "*16");
                r++;
            }

            Row sum = sheet.createRow(r);
            cell(sum, 2, head).setCellValue("合計");
            cell(sum, 3, yen).setCellFormula("SUM(D2:D" + r + ")");
            cell(sum, 4, yen).setCellFormula("SUM(E2:E" + r + ")");

            int[] widths = {12, 16, 14, 12, 18};                 // 文字数の目安
            for (int i = 0; i < widths.length; i++) {
                sheet.setColumnWidth(i, widths[i] * 256);        // 単位は 1/256 文字
            }
            sheet.createFreezePane(0, 1);                         // 1行目を固定
            sheet.setAutoFilter(new CellRangeAddress(0, r - 1, 0, titles.length - 1));
            wb.setForceFormulaRecalculation(true);                // 開いたときに数式を計算し直す

            wb.write(out);
        }
    }

    static Cell cell(Row row, int col, CellStyle style) {
        Cell c = row.createCell(col);
        c.setCellStyle(style);
        return c;
    }

    static void border(CellStyle s) {
        s.setBorderTop(BorderStyle.THIN);
        s.setBorderBottom(BorderStyle.THIN);
        s.setBorderLeft(BorderStyle.THIN);
        s.setBorderRight(BorderStyle.THIN);
    }
}

書き込みのポイント

大量のデータを書き出す：SXSSF

XSSFWorkbook は全部のセルをメモリに置くため、数十万行を書くとメモリが足りなくなります。SXSSFWorkbook は、直近の行（既定は100行）だけをメモリに置き、それより前の行を一時ファイルに書き出しながら進みます。

import java.io.FileOutputStream;

import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.xssf.streaming.SXSSFSheet;
import org.apache.poi.xssf.streaming.SXSSFWorkbook;

public class WriteLargeExcel {

    public static void main(String[] args) throws Exception {
        SXSSFWorkbook wb = new SXSSFWorkbook(100);   // メモリに置く行数
        wb.setCompressTempFiles(true);                // 一時ファイルを gzip で小さくする
        try (FileOutputStream out = new FileOutputStream("large.xlsx")) {
            SXSSFSheet sheet = wb.createSheet("明細");
            sheet.trackAllColumnsForAutoSizing();     // autoSizeColumn を使うなら書く前に
            Row header = sheet.createRow(0);
            header.createCell(0).setCellValue("番号");
            header.createCell(1).setCellValue("金額");

            for (int i = 1; i <= 500_000; i++) {      // DB のカーソルなどから1行ずつ
                Row row = sheet.createRow(i);
                row.createCell(0).setCellValue(i);
                row.createCell(1).setCellValue(i * 100L);
            }
            sheet.autoSizeColumn(0);
            wb.write(out);
        } finally {
            wb.dispose();                             // 一時ファイルを消す（公式の案内どおり必ず呼ぶ）
            wb.close();
        }
    }
}

結合セル・ハイパーリンク・コメントは SXSSF でもメモリに残るため、大量に使うとメモリを使います。DB から取り出すときも、全件を List に入れずに1行ずつ書くと、Java 側のメモリも抑えられます。

大きなファイルを読む

読み込みには SXSSF のような仕組みがありません。XSSFWorkbook で数十万行のファイルを開くと、ファイルの数倍以上のメモリを使います。行を順に読むだけなら、POI の XSSFReader（SAX 形式のイベント読み込み）や、それを包んだ外部ライブラリでストリーミングして読みます。

Spring Boot で Excel をダウンロードさせる

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import jakarta.servlet.http.HttpServletResponse;

@RestController
public class ExcelDownloadController {

    @GetMapping("/employees.xlsx")
    public void download(HttpServletResponse response) throws Exception {
        String fileName = URLEncoder.encode("社員一覧.xlsx", StandardCharsets.UTF_8).replace("+", "%20");
        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
        response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + fileName);

        try (Workbook wb = new XSSFWorkbook()) {
            wb.createSheet("社員").createRow(0).createCell(0).setCellValue("社員番号");
            wb.write(response.getOutputStream());       // ファイルを作らずに直接返す
        }
    }
}

• 日本語のファイル名は filename*=UTF-8'' の形（RFC 6266・RFC 5987）で、URL エンコードして渡します
• .xlsx の Content-Type は application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、.xls は application/vnd.ms-excel です
• 大量の行なら SXSSFWorkbook にし、finally で dispose() します

よくあるエラーと対処

よくある質問

Q. .xls と .xlsx の両方を読む必要があります。 A. WorkbookFactory.create(file) がファイルの中身を見て HSSFWorkbook か XSSFWorkbook を作るので、コードは Workbook インターフェースで書けば1本で済みます。

Q. 既存の Excel のひな形に値を書き込みたいです。 A. WorkbookFactory.create(new FileInputStream("template.xlsx")) で開き、getRow()／getCell() で場所を取って値を入れ、別のファイル名で保存します。File で開いたブックを同じファイルに書き戻すと、読み込み中のファイルを上書きすることになるため避けます。

Q. CSV と POI のどちらで出力すべきですか。 A. 書式・複数シート・数式が要るなら POI、データの受け渡しだけなら CSV が軽くて速い形です。CSV を Excel で開く場合は、文字コード（BOM 付き UTF-8 など）と、0埋めの番号が数値に変わる点に注意します。

Q. POI はスレッドセーフですか。 A. 1つの Workbook を複数のスレッドから同時に操作するのは避けます。ファイルごとに別の Workbook を作れば、並行して処理できます。

まとめ

• 依存は poi-ooxml を1つ。読み込みは WorkbookFactory.create()、書き込みは XSSFWorkbook、大量出力は SXSSFWorkbook
• 値は DataFormatter で表示どおりに、型が要るなら getCellType() で分けて読む。日付は DateUtil.isCellDateFormatted で判定する
• 数式は FormulaEvaluator で計算して読み、書いたら setForceFormulaRecalculation(true)
• 書式（CellStyle）は最初に作って使い回す。セルごとに作ると上限を超える
• 大量出力は SXSSF。finally で dispose() して一時ファイルを消す
• Spring Boot のダウンロードは filename*=UTF-8'' で日本語のファイル名を渡す

参考・出典

確認日はいずれも 2026年10月10日です。

• Apache POI「Download」（5.5.1）：https://poi.apache.org/download.html
• Apache POI「Busy Developers' Guide to HSSF and XSSF Features」：https://poi.apache.org/components/spreadsheet/quick-guide.html
• Apache POI「How to use the HSSF API（SXSSF を含む）」：https://poi.apache.org/components/spreadsheet/how-to.html
• Apache POI「Formula Evaluation」：https://poi.apache.org/components/spreadsheet/eval.html
• Apache POI Javadoc「DataFormatter」「DateUtil」「SXSSFWorkbook」：https://poi.apache.org/apidocs/5.0/
• Microsoft サポート「Excel の仕様と制限」：https://support.microsoft.com/ja-jp/office/excel-の仕様と制限-1672b34d-7043-467e-8e27-269d656771c3
• RFC 6266「Use of the Content-Disposition Header Field in HTTP」：https://www.rfc-editor.org/rfc/rfc6266
• itsakura「Java Apache POIでエクセルを操作するサンプル」：https://itsakura.com/java-poi

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。