설치¶
요구사항¶
아래의 모든 예제는 Python 가상 환경 내에서 실행 중이라고 가정합니다. 자세한 내용은 https://docs.python.org/3/library/venv.html 을 참조하세요. 또한 pip 가 최신 버전이라고 가정합니다.
예를 들어:
Windows:
py -m venv pymupdf-venv .\pymupdf-venv\Scripts\activate python -m pip install --upgrade pip
Linux, MacOS:
python -m venv pymupdf-venv . pymupdf-venv/bin/activate python -m pip install --upgrade pip
설치¶
PyMuPDF 는 다음 명령으로 pip를 사용하여 설치해야 합니다:
pip install --upgrade pymupdf
플랫폼에 사용 가능한 Python wheel이 있으면 이를 사용하여 설치됩니다.
적합한 wheel 파일을 사용할 수 없는 경우의 설치¶
적합한 Python wheel 파일을 사용할 수 없는 경우, pip는 Python sdist를 사용하여 소스에서 자동으로 빌드합니다.
이를 위해서는 C/C++ 개발 도구가 설치되어 있어야 합니다:
Windows에서:
Visual Studio 2019를 설치하세요. 표준 위치에 설치되지 않은 경우, 환경 변수
PYMUPDF_SETUP_DEVENV를devenv.com바이너리의 위치로 설정하세요.Visual Studio 2022와 같은 다른 버전의 Visual Studio가 설치되어 있으면, MuPDF와 PyMuPDF 코드가 서로 다른 컴파일러 버전으로 컴파일될 수 있어 문제가 발생할 수 있습니다.
빌드는 자동으로 MuPDF를 다운로드하고 빌드합니다.
설치 후 문제¶
Windows에서 Python 오류:
ImportError: DLL load failed while importing _extra
MSVCP140.dll이 누락된 경우 가끔 발생하며, 일부 버전(2015-2017)의Microsoft Visual C++ 재배포 가능 패키지의 버그로 인한 것으로 보입니다.https://msdn.com 에서
MSVCP140.dll을 검색하여 재설치 방법을 찾는 것이 좋습니다. 예를 들어 https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist 에는 지원되는 최신 버전에 대한 영구 링크가 있습니다.자세한 내용은 https://github.com/pymupdf/PyMuPDF/issues/2678 을 참조하세요.
Python 오류:
ModuleNotFoundError: No module named 'frontend'
PyMuPDF의 레거시 이름
fitz를 사용하는 경우(예:import pymupdf대신import fitz) 및 관련 없는 Python 패키지fitz(https://pypi.org/project/fitz/)가 설치된 경우 발생할 수 있습니다.fitz 패키지는 더 이상 유지 관리되지 않는 것으로 보입니다(최신 릴리스는 2017년). 불행히도 pypi.org에서 제거하는 것은 불가능해 보입니다. 자체적으로도 작동하지 않으며 PyMuPDF의 레거시 이름 사용도 방해합니다.
이 문제를 피하는 몇 가지 방법이 있습니다:
import fitz대신import pymupdf를 사용하고 코드를 업데이트하세요.또는
fitz패키지를 제거하고 PyMuPDF를 재설치하세요:pip uninstall fitz pip install --force-reinstall pymupdf
또는
import pymupdf as fitz를 사용하세요. 다만 이 방법은 충분히 테스트되지 않았습니다.
Apple Silicon(arm64)의 Jupyter labs에서 Python 오류:
ImportError: /opt/conda/lib/python3.11/site-packages/pymupdf/libmupdf.so.24.4: undefined symbol: fz_pclm_write_options_usage
이는 Jupyter labs의 문제로 보입니다. 자세한 내용은 https://github.com/pymupdf/PyMuPDF/issues/3643#issuecomment-2210588778 을 참조하세요.
Windows에서 Python 오류:
ImportError: dynamic module does not define module export function (PyInit__extra)
이 문제는 2025-03-26에 https://github.com/pymupdf/PyMuPDF/issues/4405 에서 보고되었습니다.
해결 방법은 최신
VC_redist.x64.exe를 설치하는 것으로 보입니다.
참고사항¶
다음 플랫폼에 대해 wheel 파일을 사용할 수 있습니다:
Windows 32비트 Intel.
Windows 64비트 Intel.
Linux 64비트 Intel.
Linux 64비트 ARM.
MacOS 64비트 Intel.
MacOS 64비트 ARM.
세부사항:
위 플랫폼 각각에 대해 단일 wheel 파일을 릴리스합니다.
각 wheel은 현재 지원되는 가장 오래된 Python 버전(현재 3.10)의 Python Stable ABI를 사용하므로, 새로운 Python 릴리스를 포함한 모든 이후 Python 버전에서 작동합니다.
Wheel은 https://devguide.python.org/versions/ 에서 현재 “지원됨”으로 표시된 모든 Python 버전에서 테스트되며, 현재 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14 입니다.
Windows에서 Chocolatey 로 설치한 Python에는 wheel 파일을 사용할 수 없습니다. 대신 python.org 웹사이트의 Windows 설치 프로그램을 사용하여 Python을 설치하세요. 자세한 내용은 http://www.python.org/downloads 를 참조하세요.
Musl libc 를 사용하는 Linux-aarch64(예: aarch64의 Alpine Linux)에는 wheel 파일을 사용할 수 없으며, 소스에서 빌드하는 것은 실패하는 것으로 알려져 있습니다.
필수 외부 종속성은 없습니다. 다만 일부 선택적 기능은 추가 구성 요소가 설치된 경우에만 사용할 수 있습니다:
Pillow 는
Pixmap.pil_save()및Pixmap.pil_tobytes()에 필요합니다.fontTools 는
Document.subset_fonts()에 필요합니다.pymupdf-fonts 는 텍스트 출력 방법에 사용할 수 있는 좋은 글꼴 모음입니다.
이미지 및 문서 페이지의 광학 문자 인식을 위한 Tesseract-OCR 입니다. Tesseract는 별도의 소프트웨어이며 Python 패키지가 아닙니다. PyMuPDF에서 OCR 기능을 사용하려면 Tesseract를 설치하고
tessdata폴더 이름을 지정해야 합니다. 아래를 참조하세요.
참고
이러한 추가 구성 요소는 언제든지 설치할 수 있습니다 – PyMuPDF 설치 전후 모두 가능합니다. PyMuPDF는 가져오기 중 또는 해당 함수가 사용될 때 이들의 존재를 감지합니다.
로컬 PyMuPDF 소스 트리에서 빌드 및 설치¶
초기 설정:
위에 설명된 대로 C/C++ 개발 도구를 설치하세요.
위에 설명된 대로 Python venv에 들어가서 pip를 업데이트하세요.
PyMuPDF 소스 트리 가져오기:
PyMuPDF git 저장소 복제:
git clone https://github.com/pymupdf/PyMuPDF.git
또는 https://github.com/pymupdf/PyMuPDF/releases 에서
.zip또는.tar.gz소스 릴리스를 다운로드하고 압축을 풀 수 있습니다.
그런 다음 PyMuPDF를 두 가지 방법으로 빌드할 수 있습니다:
기본 MuPDF 버전으로 PyMuPDF 빌드 및 설치:
cd PyMuPDF && pip install .
이렇게 하면 특정 하드코딩된 MuPDF 소스 릴리스를 자동으로 다운로드하여 PyMuPDF에 빌드합니다.
또는 로컬 MuPDF 소스 트리를 사용하여 PyMuPDF 빌드 및 설치:
MuPDF git 저장소 복제:
git clone --recursive https://git.ghostscript.com/mupdf.git
환경 변수
PYMUPDF_SETUP_MUPDF_BUILD를 사용하여 로컬 MuPDF 트리의 위치를 지정하여 PyMuPDF 빌드:cd PyMuPDF && PYMUPDF_SETUP_MUPDF_BUILD=../mupdf pip install .
또한 동일한 PyMuPDF 트리에서 다른 Python 버전용으로 빌드할 수 있습니다:
PyMuPDF는
pip를 실행하는 데 사용되는 Python 버전에 대해 빌드됩니다. 특정 Python 버전으로pip를 실행하려면pip대신python -m pip를 사용하세요.예를 들어 Windows에서 다음과 같이 다른 버전을 빌드할 수 있습니다:
cd PyMuPDF && py -3.10 -m pip install .
또는:
cd PyMuPDF && py -3.10-32 -m pip install .
테스트 실행¶
PyMuPDF 트리를 사용할 수 있으면 PyMuPDF의 pytest 테스트 스위트를 실행할 수 있습니다:
pip install pytest fontTools
pytest PyMuPDF/tests
기본값이 아닌 MuPDF 사용에 대한 참고사항¶
환경 변수 PYMUPDF_SETUP_MUPDF_BUILD 를 설정하여 기본값이 아닌 MuPDF 빌드를 사용하면 다양한 문제가 발생할 수 있으므로 일반적으로 지원되지 않습니다:
MuPDF의 주 버전 번호가 PyMuPDF가 기본적으로 사용하는 것과 다르면, MuPDF의 API가 주 버전 간에 변경될 수 있으므로 PyMuPDF 빌드가 실패할 수 있습니다.
PyMuPDF의 런타임 동작은 MuPDF의 런타임 동작이 다른 부 버전 간에 변경되기 때문에 변경될 수 있습니다. 이로 인해 일부 PyMuPDF 테스트가 실패할 수도 있습니다.
MuPDF가 PyMuPDF의 사용자 정의 구성 대신 기본 구성을 사용하여 빌드된 경우(예: MuPDF가 시스템 설치인 경우),
tests/test_textbox.py:test_textbox3()가 실패할 수 있습니다.pytest명령줄에-k 'not test_textbox3'를 추가하여 이 특정 테스트를 건너뛸 수 있습니다.
공식 PyMuPDF Linux wheel 파일이 오래된 Linux 시스템에 설치되지 않을 수 있음¶
PyMuPDF 릴리스는 오래된 Linux 시스템과 호환되지 않습니다.
예를 들어 2025-09-03 기준으로, 일부 AWS Lambda 시스템에서는 pip install pymupdf 가 작동하지 않습니다. 자세한 내용은 https://github.com/pymupdf/PyMuPDF/discussions/4631 을 참조하세요.
이는 공식 PyMuPDF Linux wheel 파일이 현재 Python manylinux 환경에 의해 결정된 glibc 버전으로 빌드되기 때문입니다. 이러한 wheel 파일은 오래된 glibc를 가진 Linux 시스템과 호환되지 않습니다.
공식 Python manylinux 환경은 최신 glibc 버전을 사용하도록 주기적으로 업데이트되므로, PyMuPDF의 새 릴리스는 오래된 Linux 시스템과 점점 더 호환되지 않게 됩니다.
오래된 Linux 시스템을 업데이트하거나 소스에서 로컬로 PyMuPDF를 빌드하는 것 외에는 이에 대해 할 수 있는 일이 없습니다.
자세한 내용은 Python Packaging Authority 를 참조하세요.
패키징¶
Linux 배포판용 패키징 을 참조하세요.
Pyodide와 함께 사용¶
Pyodide 를 참조하세요.
통합 OCR 지원 활성화¶
PyMuPDF will already contain all the logic to support OCR functions. But it additionally does need Tesseract’s language support data.
If not specified explicitly, PyMuPDF will attempt to find the installed
Tesseract’s tessdata, but this should probably not be relied upon.
그렇지 않으면 PyMuPDF는 Tesseract의 언어 지원 폴더가 PyMuPDF OCR 함수의 tessdata 인수 또는 os.environ["TESSDATA_PREFIX"] 에 명시적으로 지정되어야 합니다.
따라서 OCR 기능이 작동하려면 다음 체크리스트를 완료해야 합니다:
Tesseract의 언어 지원 폴더를 찾으세요. 일반적으로 다음 위치에 있습니다:
Windows:
C:/Program Files/Tesseract-OCR/tessdataUnix 시스템:
/usr/share/tesseract-ocr/4.00/tessdata
PyMuPDF OCR 함수를 호출할 때 언어 지원 폴더를 지정하세요:
tessdata인수를 설정하세요.또는 Python 내에서
os.environ["TESSDATA_PREFIX"]를 설정하세요.또는 Python을 실행하기 전에 환경 변수
TESSDATA_PREFIX를 설정하세요. 예:Windows:
setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata"Unix 시스템:
declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata
참고
English language support is included by default in Tesseract installation.
Tesseract Language Packs for other languages must be installed separately, and the tessdata folder must be specified to PyMuPDF as described above, for OCR to work with those languages.
참고
Find out more on the official documentation for installing Tesseract website.