EPUBCheck 5.4.0은 EPUB 2와 EPUB 3 전자책이 규격에 맞는지 확인하는 무료 공식 검사기입니다. W3C를 대신해 DAISY Consortium이 유지하며, 실행용 ZIP을 풀고 Java에서 epubcheck.jar를 실행합니다.
공식 5.4.0 ZIP과 휴대용 Java로 유효한 EPUB 3.4 샘플과 중복 id·누락 링크가 있는 오류 샘플을 직접 검사했습니다. ZIP 선택, Java 준비, 전체·expanded·단일 파일 검사, JSON·XML 보고서, 종료 코드와 실제 RSC-005·RSC-007 오류 해결까지 설명합니다.
EPUBCheck는 어떤 전자책 검사기인가요?
EPUBCheck는 EPUB 컨테이너, package 문서, XHTML, 탐색 문서, 리소스 참조와 메타데이터가 EPUB 규격에 맞는지 검사합니다. 전자책 제작자와 출판사가 배포 전 품질 검수에 사용합니다.
기본 GUI는 없으며 PowerShell이나 터미널에서 java -jar epubcheck.jar 다음에 검사할 EPUB 경로와 옵션을 입력합니다. 결과는 콘솔, JSON, XML 또는 XMP로 남길 수 있습니다.
EPUBCheck 5.4.0 실제 명령과 검사 결과
공식 실행용 ZIP과 Java에서 –help, –version, 유효 EPUB 검사와 중복 id·누락 리소스가 있는 오류 EPUB 검사를 직접 실행했습니다. 실제 콘솔의 지원 모드, 0 errors 통과와 3 errors 실패 요약입니다.
| 전체 EPUB | file.epub |
|---|---|
| 압축 해제판 | –mode exp |
| JSON 보고서 | –json |
| XML 보고서 | –out |
| 경고 실패 | –failonwarnings |
| 언어 선택 | –locale |
ZIP 설치부터 첫 EPUB 검사까지
EPUBCheck 5.4.0은 EPUB 2와 EPUB 3 출판물이 규격에 맞는지 검사하는 무료 오픈소스 명령줄 도구입니다. 공식 ZIP을 풀고 Java에서 epubcheck.jar를 실행하며 별도의 기본 GUI는 없습니다.
첫 검사는 java -jar epubcheck.jar –version으로 5.4.0을 확인한 뒤 java -jar epubcheck.jar book.epub을 실행합니다. 마지막 Messages 요약이 0 errors / 0 warnings인지, 오류가 있으면 메시지 ID와 파일·줄 번호가 무엇인지 확인하면 작업이 끝납니다.
- epubcheck-5.4.0.zip을 받아 새 폴더에 풉니다.
- java -version으로 Java 실행 여부를 확인합니다.
- epubcheck.jar와 lib 폴더를 같은 위치에 둡니다.
- java -jar epubcheck.jar –version을 실행합니다.
- java -jar epubcheck.jar book.epub을 실행합니다.
- 요약과 오류 위치를 보고 EPUB 원본을 고친 뒤 다시 검사합니다.
5.4.0 무료 오픈소스와 검사 범위
W3C의 공식 저장소는 EPUBCheck를 DAISY Consortium이 W3C를 대신해 유지하는 공식 EPUB 적합성 검사기로 설명합니다. 5.4.0은 2026년 9월 15일 공개된 최신 production-ready 릴리스이며 3-Clause BSD 라이선스로 배포됩니다.
5.4.0은 EPUB 2와 EPUB 3을 검사하고 최신 EPUB 3.4 후보 권고의 적합성 검사도 지원합니다. EPUB 파일의 ZIP 구조, package 문서, XHTML, 탐색 문서, 리소스 참조와 접근성 관련 규칙을 함께 확인합니다.
공식 ZIP 파일 선택
일반 사용자는 릴리스 자산인 epubcheck-5.4.0.zip 하나를 받습니다. 실제 파일 크기는 33,093,170바이트이며 소스 코드 ZIP이 아니라 실행용 배포 ZIP을 선택해야 합니다.
압축을 풀면 epubcheck.jar와 lib 폴더가 있습니다. jar만 다른 폴더로 옮기면 의존 라이브러리를 찾지 못할 수 있으므로 전체 폴더 구조를 함께 보관합니다.
Java 준비와 버전 확인
공식 설치 문서는 명령줄 실행에 Java 7 이상이 필요하다고 안내합니다. java -version이 명령으로 인식되지 않으면 64비트 JRE 또는 JDK를 설치하고 새 PowerShell에서 다시 확인합니다.
EPUBCheck 폴더에서 java -jar epubcheck.jar –version을 실행했을 때 EPUBCheck v5.4.0이 표시되면 jar와 Java 경로가 연결된 것입니다.
PowerShell에서 EPUB 한 권 검사
검사할 EPUB을 작업 폴더에 두고 java -jar epubcheck.jar "book.epub"을 실행합니다. 경로에 공백이 있으면 반드시 큰따옴표로 감쌉니다.
정상 파일은 Validating using EPUB version 문구 뒤 No errors or warnings detected와 0 errors 요약이 나타납니다. 오류가 있으면 종료 코드도 1이므로 자동화에서는 출력과 종료 코드를 함께 기록합니다.
ERROR 메시지의 파일과 줄 읽기
ERROR(RSC-005)처럼 괄호 안은 메시지 ID입니다. 뒤에는 EPUB 내부 경로와 줄·열 위치, 오류 설명이 이어집니다. 먼저 가장 앞의 오류부터 수정하면 뒤 오류가 함께 사라지는 경우가 많습니다.
invalid-sample.epub 실검사에서는 중복 id에 RSC-005, EPUB에 포함되지 않은 missing.xhtml 링크에 RSC-007이 표시됐습니다. 해당 XHTML을 열어 id를 고유하게 바꾸고 잘못된 href를 실제 파일로 고칩니다.
JSON 보고서로 결과 저장
사람이 읽는 콘솔 출력과 별도로 –json report.json을 붙이면 구조화된 검사 보고서를 저장할 수 있습니다. 예시는 java -jar epubcheck.jar –json report.json book.epub입니다.
자동 검수에서는 report.json의 메시지 ID, severity, location을 수집하고 EPUB 파일명과 EPUBCheck 버전을 함께 남깁니다. 새 버전으로 바꿨을 때 규칙 차이를 비교하기 쉽습니다.
XML과 XMP 보고서 선택
–out report.xml은 XML 평가 문서를, –xmp report.xmp는 XMP 보고서를 만듭니다. JSON과 XML은 다른 시스템에 전달할 때 적합하고 콘솔 출력은 한 권을 바로 확인할 때 편합니다.
보고서 파일 경로가 기존 파일과 겹치지 않게 EPUB 기본 이름을 붙입니다. 검사 실패 시에도 보고서가 만들어질 수 있으므로 파일 존재만으로 통과 처리하지 않고 errors와 warnings 수를 읽습니다.
경고를 실패로 처리하기
기본 종료 코드는 오류가 있을 때 1, 오류가 없으면 0입니다. –failonwarnings를 붙이면 경고만 있어도 1을 반환하므로 배포 전 품질 게이트에 사용할 수 있습니다.
-q 또는 –quiet는 오류가 없을 때 콘솔 메시지를 줄입니다. -w는 경고·오류·치명 오류를, -e는 오류와 치명 오류를, -f는 치명 오류만 출력하므로 보고 목적에 맞춰 선택합니다.
압축을 푼 EPUB 검사
EPUB을 폴더로 풀어 수정 중이라면 java -jar epubcheck.jar folder -mode exp로 expanded EPUB을 검사합니다. 완성된 .epub 전체 검사와 달리 작업 폴더 구조를 직접 읽습니다.
-save를 함께 쓰면 검사한 expanded EPUB을 다시 EPUB 파일로 저장할 수 있습니다. 배포 전에는 생성된 .epub을 다시 일반 모드로 한 번 더 검사합니다.
package·XHTML·nav 단일 파일 검사
전체 EPUB이 아니라 구성 파일만 확인할 때 –mode opf, xhtml, nav, svg, mo와 -v 버전을 지정할 수 있습니다. 예를 들어 content.xhtml –mode xhtml -v 3.0처럼 실행합니다.
단일 파일 검사는 전체 책의 manifest, spine과 리소스 연결을 모두 확인하지 않습니다. 부분 수정 중 빠른 확인에 쓰고 최종 배포 전에는 .epub 전체를 다시 검사합니다.
File not found 해결
File not found가 나오면 현재 폴더에서 Test-Path "book.epub"으로 파일 존재를 확인하고 전체 경로를 큰따옴표로 감싸 실행합니다. 탐색기에서 확장자가 숨겨져 book.epub.zip으로 저장되지 않았는지도 봅니다.
EPUBCheck ZIP을 푼 폴더와 검사할 EPUB 폴더가 다르면 epubcheck.jar와 book.epub 모두 전체 경로로 지정합니다. 상대 경로는 현재 PowerShell 위치를 기준으로 계산됩니다.
Unable to access jarfile 해결
Unable to access jarfile epubcheck.jar는 jar 경로가 틀렸다는 뜻입니다. Get-ChildItem -Recurse -Filter epubcheck.jar로 실제 위치를 찾고 java -jar 뒤에 그 전체 경로를 넣습니다.
jar만 복사하고 lib 폴더를 빼먹지 않습니다. 공식 배포 ZIP을 새 폴더에 다시 풀어 epubcheck.jar와 lib가 함께 있는 상태에서 –version을 먼저 확인합니다.
중복 ID와 잘못된 링크 고치기
Duplicate ID 메시지는 같은 XHTML 안에서 id 값이 두 번 이상 쓰였을 때 발생합니다. 각 id를 고유하게 바꾸고 목차·본문 링크의 #fragment도 새 id에 맞춥니다.
리소스가 EPUB에 포함되지 않았다는 RSC-007은 href나 src가 실제 파일을 가리키는지, manifest에 등록됐는지, 대소문자가 정확한지 확인합니다. Windows에서 보이는 파일명 대소문자도 EPUB 내부에서는 구분될 수 있습니다.
mimetype와 ZIP 구조 오류 해결
EPUB의 mimetype 파일은 ZIP의 첫 항목이어야 하고 압축하지 않은 상태로 application/epub+zip 내용을 가져야 합니다. 일반 압축 프로그램으로 폴더 전체를 다시 압축하면 이 조건이 깨질 수 있습니다.
container.xml의 rootfile 경로가 실제 package.opf 위치와 맞는지 확인합니다. 구조를 고친 뒤 같은 파일을 다시 검사하고 OCF 관련 오류가 사라졌는지 봅니다.
EPUB 버전과 profile 지정
완성된 .epub 파일은 package 문서에서 버전을 읽으므로 보통 -v를 따로 지정하지 않습니다. dict, edupub, idx, preview 같은 확장 규격을 명시적으로 검사해야 할 때만 –profile 이름을 붙입니다.
profile을 억지로 지정하기 전에 package 문서의 dc:type과 실제 출판물 성격을 확인합니다. 일반 전자책은 기본 profile로 전체 검사를 실행하고, 특정 확장 규격을 적용하는 경우에만 해당 profile 결과를 추가로 남깁니다.
검사 메시지 언어 바꾸기
–locale en처럼 IETF BCP 47 언어 태그를 지정하면 출력 메시지 언어를 정할 수 있습니다. 팀에서 오류 메시지를 공유할 때는 같은 locale을 사용해야 메시지 본문과 검색 결과가 일치합니다.
번역이 달라도 RSC-005 같은 메시지 ID와 파일·줄 위치는 같은 문제를 가리킵니다. 해결 기록에는 번역된 문장만 복사하지 말고 메시지 ID, severity와 EPUB 내부 경로를 함께 적습니다.
여러 EPUB을 연속 검사
폴더의 여러 .epub을 검사할 때는 각 파일마다 java -jar epubcheck.jar를 실행하고 종료 코드와 보고서 이름을 따로 저장합니다. 한 권이 실패해도 다음 파일의 검사 결과를 덮어쓰지 않습니다.
보고서 이름은 책 이름과 버전을 포함해 충돌을 막고, 검사 완료 뒤 오류 수가 0인 파일과 수정이 필요한 파일을 분리합니다. 배치 실행이 끝났다는 사실만으로 모든 EPUB이 통과했다고 판단하지 않습니다.
접근성·usage 메시지 검토
-u 또는 –usage는 EPUB 기능 사용 정보를 보고서에 포함합니다. 이는 오류만 찾는 것과 달리 어떤 EPUB 기능이 쓰였는지 파악할 때 도움이 됩니다.
접근성 메타데이터와 대체 텍스트 관련 메시지는 단순히 오류 수를 줄이기 위해 숨기지 않습니다. 출판 플랫폼의 접근성 요구 사항과 EPUB 규격을 함께 확인하고 원본 콘텐츠에서 문제를 수정한 뒤 다시 검사합니다.
버전과 결과를 함께 보관
검사 기록에는 EPUBCheck v5.4.0, 실행 명령, 검사 대상 파일 해시, 종료 코드와 JSON 보고서를 함께 남깁니다. 같은 EPUB도 도구 버전과 지원 규격이 바뀌면 새 메시지가 생길 수 있습니다.
전자책을 수정한 뒤에는 이전 통과 결과를 재사용하지 말고 새 파일을 다시 검사합니다. 0 errors만 보지 말고 warnings와 usage 메시지도 출판 플랫폼 요구 사항에 맞춰 검토합니다.
자주 묻는 질문
EPUBCheck 5.4.0은 무료인가요?
예. W3C 공식 저장소에서 3-Clause BSD 라이선스의 오픈소스로 배포합니다.
어떤 파일을 받나요?
릴리스 자산의 epubcheck-5.4.0.zip을 받습니다. 소스 코드 ZIP이 아니라 epubcheck.jar와 lib가 들어 있는 실행용 배포 ZIP입니다.
설치 프로그램이 없는데 어떻게 실행하나요?
ZIP을 풀고 Java를 준비한 뒤 epubcheck.jar의 버전 확인 옵션을 실행합니다. EPUBCheck는 기본 GUI가 없는 명령줄 도구입니다.
EPUB 한 권은 어떻게 검사하나요?
java -jar epubcheck.jar "book.epub"을 실행하고 마지막 errors와 warnings 요약을 확인합니다.
검사 결과를 파일로 남길 수 있나요?
JSON, XML 또는 XMP 출력 옵션과 보고서 파일명을 지정해 결과를 저장할 수 있습니다.
5.4.0을 확인하고 EPUB 오류를 하나씩 고치세요
실행용 ZIP을 전체 해제하고 epubcheck.jar의 버전 확인 옵션에서 5.4.0을 확인합니다. book.epub을 검사해 메시지 ID와 내부 파일·줄 번호를 보고 첫 오류부터 수정하세요. 다시 실행해 0 errors를 확인하고 JSON 보고서와 버전, 대상 파일 해시를 함께 보관하면 배포 전 검수가 끝납니다.
공식 자료와 확인일
EPUBCheck 공식 저장소 · EPUBCheck 5.4.0 공식 릴리스 · EPUBCheck 공식 설치 문서 · EPUBCheck 공식 실행 문서 · EPUBCheck 공식 오류 메시지 문서 | 2026-10-01T21:58:43.559933+00:00
