내 PC에서 직접 운영하는 PDF 처리·편집 도구 - PDF Toolkit

Python + FastAPI + Uvicorn 기반의 로컬 자체 호스팅 PDF 처리·편집 도구로, 브라우저에서 PDF 병합·분할·페이지 관리·콘텐츠 편집

2026-11-19 (목) 19:24:35 조회 5
문의하기
내 PC에서 직접 운영하는 PDF 처리·편집 도구 - PDF Toolkit
Python FastAPI Uvicorn pypdf PyMuPDF ReportLab Pillow Jinja2 HTML5 CSS3 JavaScript REST API

우리가 PDF 문서를 다루다 보면 여러 프로그램이나 온라인 서비스를 이용하게 됩니다.

여러 PDF를 하나로 합치거나 필요한 페이지만 추출하고, 페이지 순서를 변경하거나 문서에 텍스트와 이미지를 추가하는 작업 등이 그렇습니다.

간단한 작업인데도 별도의 프로그램을 설치해야 하거나, 온라인 서비스에 파일을 업로드해야 하는 경우가 있습니다. 사용하려는 기능이 제공되지 않으면 다른 도구를 찾거나 프로그램의 업데이트를 기다려야 하기도 합니다.

최근 Python과 AI 개발 도구를 활용해 이미지, 오디오, 동영상 등 여러 작업 도구를 구성하면서, PDF도 같은 방식으로 직접 운영하고 필요에 따라 수정할 수 있으면 좋겠다는 생각을 했습니다.

그렇게 구성한 프로젝트가 PDF Toolkit입니다.

PDF Toolkit은 Python + FastAPI + Uvicorn 기반의 브라우저형 PDF 처리·편집 도구입니다. 자신의 PC 또는 서버에서 직접 실행하고, 웹 브라우저를 통해 PDF를 처리하거나 편집할 수 있도록 만들었습니다.

현재 v1.0.0 정식 버전을 GitHub에 공개했습니다.


1. PDF Toolkit에서 할 수 있는 작업

PDF Toolkit은 하나의 화면에서 세 가지 작업 공간을 제공합니다.

① PDF 도구 (PDF Tools)

PDF 파일을 처리하는 11가지 기능을 제공합니다.

기능 설명
PDF 병합 PDF 2~10개를 지정한 순서대로 하나로 합치기
페이지 추출 필요한 페이지나 페이지 범위를 별도 PDF로 저장
PDF 분할 페이지별 또는 지정 범위별로 분할하고 ZIP으로 다운로드
페이지 회전 선택한 페이지를 90°·180°·270° 회전
페이지 이미지 변환 지정 페이지를 PNG 또는 JPEG로 변환
PDF 최적화 PDF 내부 데이터를 최적화하여 파일 크기 감소 시도
문자 워터마크 영문·숫자 등 ASCII 문자 워터마크 삽입
PDF 암호 보호 결과 PDF에 열기 암호 설정
텍스트 추출 선택 가능한 PDF 텍스트를 TXT 파일로 추출
Unicode 워터마크 한글 등 Unicode 문자 워터마크 삽입
이미지 워터마크 로고 등의 PNG/JPEG 이미지를 워터마크로 삽입

예를 들어 여러 개의 PDF 자료를 하나로 합치거나, 문서에서 3~5페이지만 추출해 별도의 파일로 만들 수 있습니다.

텍스트 추출은 PDF에 포함된 선택 가능한 문자를 대상으로 하며, 스캔 이미지의 문자를 인식하는 OCR 기능은 포함하지 않습니다.

② 페이지 편집기 (Page Editor)

PDF 문서의 페이지 구성을 변경하는 작업 공간입니다.

PDF를 불러오면 각 페이지가 썸네일로 표시됩니다. 여기서 페이지를 선택하거나 드래그해 순서를 바꾸고, 필요 없는 페이지를 삭제하거나 선택한 페이지를 회전할 수 있습니다.

사용 순서

  1. 상단에서 페이지 편집기를 선택합니다.
  2. PDF 파일을 선택하고 페이지 불러오기를 누릅니다.
  3. 페이지 썸네일을 확인합니다.
  4. 드래그 또는 이동 버튼으로 페이지 순서를 변경합니다.
  5. 필요한 페이지를 선택해 회전하거나 삭제합니다.
  6. 편집 PDF 저장을 누릅니다.
  7. 새로 생성된 PDF 파일을 다운로드합니다.

편집 중의 페이지 구성은 우선 브라우저에서 관리되며, 저장할 때 서버가 변경 내용을 적용한 새로운 PDF를 생성합니다.

따라서 원본 PDF 파일을 직접 덮어쓰는 방식은 아닙니다.

③ 콘텐츠 편집기 (Content Editor)

PDF 페이지 위에 텍스트나 이미지를 추가하고, 지정한 영역의 내용을 제거하거나 대체하는 작업 공간입니다.

주요 기능은 다음과 같습니다.

  • 텍스트 추가 및 추가한 텍스트 수정
  • 글자 크기, 색상, 정렬, Bold/Italic 설정
  • Unicode 글꼴을 이용한 한글 텍스트 삽입
  • PNG/JPEG 이미지 추가
  • 이미지 위치 및 크기 변경
  • 이미지 90° 회전
  • 객체 선택과 드래그 이동
  • 페이지 확대·축소
  • 여러 페이지 편집
  • Undo/Redo
  • 지정 영역 제거 및 대체

사용 순서

  1. 콘텐츠 편집기를 선택합니다.
  2. PDF 파일을 선택하고 PDF 불러오기를 누릅니다.
  3. 편집할 페이지로 이동합니다.
  4. 텍스트 추가를 선택하고 원하는 위치를 클릭합니다.
  5. 문장을 입력하고 글자 크기·색상 등을 설정합니다.
  6. 필요하면 이미지 추가로 이미지를 배치합니다.
  7. 객체를 이동하거나 크기를 조절합니다.
  8. 콘텐츠 PDF 저장을 눌러 결과 파일을 다운로드합니다.

한글 등의 Unicode 문자를 PDF에 저장하려면 해당 문자를 지원하는 TTF/OTF 글꼴이 필요할 수 있습니다.

여기서 콘텐츠 편집의 범위는 구분할 필요가 있습니다.

PDF Toolkit은 텍스트·이미지 추가와 지정 영역 제거·대체를 지원하지만, 기존 PDF에 포함된 모든 텍스트나 이미지를 워드프로세서처럼 자유롭게 선택하여 수정하는 편집기는 아닙니다.

지정 영역 제거에는 PyMuPDF의 redaction 처리를 사용하므로, 제거 범위를 정확히 선택해야 합니다.


2. 설치 및 실행 방법

PDF Toolkit은 Python 애플리케이션입니다.

기본적인 로컬 사용에는 별도의 Nginx나 Apache 웹 서버, Docker 또는 외부 데이터베이스가 필요하지 않습니다.

Python 가상환경을 만들고 필요한 패키지를 설치한 뒤 Uvicorn으로 실행하면 됩니다.

Linux 설치

먼저 GitHub 저장소를 내려받습니다.

git clone https://github.com/glitter-node/pdf-toolkit.git
cd pdf-toolkit

Python 가상환경을 생성하고 의존성을 설치합니다.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Uvicorn을 실행합니다.

.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8013

브라우저에서 다음 주소를 엽니다.

http://127.0.0.1:8013/

정상적으로 실행되면 PDF Toolkit 화면이 표시됩니다.

상태 확인 주소는 다음과 같습니다.

http://127.0.0.1:8013/healthz

Windows 10/11 설치

Windows에서는 PowerShell을 사용할 수 있습니다.

먼저 Git을 통해 저장소를 내려받거나 GitHub에서 소스 ZIP을 내려받아 압축을 풉니다.

Git을 사용하는 경우:

git clone https://github.com/glitter-node/pdf-toolkit.git
Set-Location pdf-toolkit

Python 가상환경을 생성합니다.

py -3.11 -m venv .venv

의존성을 설치합니다.

& .\.venv\Scripts\python.exe -m pip install -r requirements.txt

애플리케이션을 실행합니다.

& .\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8013

브라우저 접속 주소는 Linux와 같습니다.

http://127.0.0.1:8013/

Python 3.11은 설치 예시이며, 다른 버전을 사용할 때는 프로젝트 의존성의 호환성을 확인해야 합니다.

Windows에서의 전체 설치 및 편집 기능은 아직 별도로 검증이 필요한 상태입니다.

Windows 로그인 시 자동 실행하도록 설정하는 방법도 문서로 제공하고 있습니다.

Windows 자동 시작 안내

이 문서는 Windows 작업 스케줄러를 사용하여 현재 사용자가 로그인할 때 PDF Toolkit을 실행하는 방법을 설명합니다.

macOS

macOS에서도 Python 가상환경과 Uvicorn을 이용하는 동일한 실행 구조를 사용할 수 있도록 안내하고 있습니다.

다만 Intel 및 Apple Silicon 환경에서의 실제 의존성 설치와 PDF 편집 기능은 별도 검증이 필요합니다.

운영체제별 자세한 내용은 GitHub README를 참고하면 됩니다.

설치 및 사용 문서


3. 실제 사용 방법

설치 후 브라우저에서 PDF Toolkit에 접속하면 PDF 도구, 페이지 편집기, 콘텐츠 편집기 중 필요한 작업을 선택할 수 있습니다.

예를 들어 PDF 여러 개를 하나로 합치려면 다음과 같이 사용합니다.

PDF 병합 예시

  1. PDF 도구에서 PDF 병합을 선택합니다.
  2. 합칠 PDF 파일을 2개 이상 선택하거나 드롭합니다.
  3. 화면에서 병합 순서를 조정합니다.
  4. PDF 처리를 누릅니다.
  5. 생성된 merged.pdf 파일을 다운로드합니다.

문서 일부만 추출하려면 페이지 추출을 선택하고 1,3-5처럼 페이지 범위를 입력할 수 있습니다.

페이지 순서를 바꾸거나 회전하려면 페이지 편집기를 이용하고, 문서 위에 문구나 이미지를 추가하려면 콘텐츠 편집기를 이용하면 됩니다.

처리 및 저장 결과는 새로운 파일로 다운로드되며, 사용자가 선택한 로컬 원본 파일을 직접 덮어쓰지 않습니다.


4. Python + FastAPI + Uvicorn을 선택한 이유

이 프로젝트에서 중요하게 생각한 부분은 PDF 처리 기능뿐만 아니라 개발 환경과 운영 환경을 가능한 한 일관되게 유지하는 것입니다.

기본 구조는 다음과 같습니다.

Browser
   │
   ▼
FastAPI + Uvicorn
   │
   ▼
PDF Processing Services
   │
   ▼
Generated PDF / ZIP / Image / TXT
   │
   ▼
Browser Download

브라우저에서는 PDF를 선택하고 미리보기를 확인하며 편집 객체를 조작합니다.

FastAPI는 브라우저의 요청을 받아 Python의 PDF 처리 라이브러리를 호출합니다.

현재 프로젝트에서는 주로 다음 라이브러리를 사용합니다.

  • pypdf: PDF 병합과 페이지 조작
  • PyMuPDF: PDF 렌더링 및 콘텐츠 편집
  • ReportLab: PDF 콘텐츠 생성
  • Pillow: 이미지 검증 및 처리

프런트엔드는 HTML, CSS, 바닐라 JavaScript를 사용합니다.

개발할 때도, 자신의 PC에서 사용할 때도 동일한 FastAPI 애플리케이션을 Uvicorn으로 실행합니다.

개발 환경에서는 필요에 따라 --reload 옵션을 추가할 수 있고, 일반적인 로컬 운영에서는 이를 제외하면 됩니다.

이 구조에서는 PDF 처리 기능을 추가하거나 수정할 때 관련 API와 Python 서비스 코드를 중심으로 작업할 수 있습니다.

물론 실제 운영체제와 Python 패키지에 따라 설치 환경의 차이는 있을 수 있습니다.


5. 자체 호스팅의 의미

PDF Toolkit은 온라인 PDF 변환 서비스를 반드시 거쳐야 하는 구조가 아닙니다.

사용자가 자신의 PC에서 실행하면 브라우저와 로컬 FastAPI 애플리케이션 사이에서 PDF 처리 요청이 이루어집니다.

별도 서버에 설치한다면 사용자가 운영하는 해당 서버에서 PDF를 처리합니다.

즉, PDF를 처리하는 애플리케이션의 실행 위치와 운영 방식을 사용자가 직접 결정할 수 있습니다.

다만 자체 호스팅이 자동으로 완전한 보안을 제공한다는 뜻은 아닙니다.

특히 인터넷에 공개할 경우에는 HTTPS, 인증, 접근 제어, 요청 제한 등의 운영 보안이 필요합니다.

현재 애플리케이션에는 PDF 업로드 검증, 파일 크기·페이지 수 제한, 동시 처리 제한 및 CSP를 비롯한 보안 응답 헤더가 구현되어 있습니다.

기본 설정에서는 PDF 업로드 30MB, 문서 최대 500페이지, 동시 PDF 처리 요청 2개 등의 제한을 적용합니다.

반면 애플리케이션 자체의 사용자 로그인이나 사용자별 파일 접근 분리 기능은 확인되지 않았으므로, 공개 운영 시에는 별도의 접근 통제 구성이 필요합니다.


6. 화면 테마와 다국어

PDF Toolkit은 세 가지 화면 테마를 제공합니다.

  • Light
  • Dark
  • Warm

언어는 네 가지를 지원합니다.

  • 한국어
  • English
  • 日本語
  • 简体中文

기본 언어는 한국어이며, 선택한 테마와 언어는 브라우저에 저장되어 다음 접속 시에도 사용할 수 있도록 구현되어 있습니다.

언어와 테마를 전환할 때 PDF 편집 작업을 새로 시작하지 않도록 구성했습니다.


7. AI 개발 도구와 개인 맞춤형 소프트웨어

PDF Toolkit을 구성하면서 관심을 둔 또 하나의 부분은 필요한 기능을 직접 구현하고 확장할 수 있는 환경입니다.

기존 프로그램을 사용할 때는 공급자가 제공하는 기능과 사용 방식에 맞춰야 하는 경우가 많습니다.

반면 소스를 직접 관리하는 프로젝트라면 필요한 기능을 추가하거나 화면과 작업 흐름을 자신의 용도에 맞게 수정할 수 있습니다.

최근에는 AI 개발 도구를 활용하여 소스를 분석하고, 기능 구현이나 수정 작업을 진행하는 방식도 가능해졌습니다.

PDF Toolkit은 FastAPI 라우터, PDF 처리 서비스, 브라우저 UI, 보안 설정 등이 분리되어 있어 이러한 개발 방식에 활용할 수 있습니다.

프로젝트 루트에는 AI 개발 도구가 참고할 수 있는 AGENTS.md도 포함했습니다.

AGENTS.md

이 문서에는 API 호환성, PDF 편집 좌표 처리, 보안, 데이터 보존, 검증 및 GitHub 배포 관련 작업 규칙을 정리했습니다.

여기서 AI는 PDF를 자동으로 편집하는 내장 기능이 아니라, 프로젝트의 소스를 분석하고 개발을 지원하는 외부 도구라는 점을 구분할 필요가 있습니다.

제가 생각하는 방향은 다음과 같습니다.

AI 개발 도구를 활용해 소스 코드를 직접 통제하고, 로컬에서 실행하는 개인 맞춤형 도구로의 전환.

PDF Toolkit은 이러한 사용 방식을 PDF 처리·편집 영역에 적용해 본 프로젝트입니다.


8. 현재 버전과 제한사항

현재 공개 버전은 v1.0.0입니다.

릴리스 준비 과정에서 기록된 검증 결과는 다음과 같습니다.

  • Python 테스트 156건 통과
  • JavaScript 테스트 35건 통과
  • Python 컴파일 및 JavaScript 구문 검사 통과
  • 의존성 검사 통과
  • 배포 ZIP 무결성 검사 통과

브라우저 자동화 E2E는 테스트 환경의 libatomic.so.1 라이브러리 누락으로 완료하지 못했습니다.

또한 Windows·macOS에서의 전체 설치와 편집 동작은 별도 확인이 필요합니다.

기능 측면에서는 OCR, PDF를 DOCX로 변환하는 범용 문서 변환, 기존 PDF 객체 전체를 자유롭게 수정하는 편집 기능 등은 현재 제공하지 않습니다.

PDF 최적화 기능도 모든 파일에서 크기가 줄어드는 것을 보장하지는 않습니다.

프로젝트 라이선스는 MIT License입니다. 소스 코드의 사용·수정·재배포는 MIT License 조건을 따르며, 프로젝트에 포함된 제3자 라이브러리와 글꼴 등은 각각의 라이선스가 적용됩니다.


9. 마무리

PDF Toolkit은 모든 PDF 편집 기능을 갖춘 상용 프로그램을 대체하기 위해 만든 프로젝트는 아닙니다.

자주 사용하는 PDF 처리 기능을 하나의 브라우저 화면에서 이용하고, 필요하면 소스를 수정하거나 새로운 기능을 추가할 수 있는 자체 호스팅 작업 도구로 구성했습니다.

특히 Python + FastAPI + Uvicorn을 이용하면 개발할 때 사용한 애플리케이션을 로컬 운영에서도 같은 방식으로 실행할 수 있다는 점이 마음에 들었습니다.

앞으로도 실제 사용하면서 필요한 기능을 보완하고, PDF 처리 및 편집 기능을 확장해 나갈 생각입니다.

관심 있는 분들은 GitHub 저장소에서 소스와 문서를 확인하거나 공개 데모를 살펴보실 수 있습니다.

  • 라이선스: MIT License

직접 설치하거나 사용해 보시고, 기능이나 사용 방식에서 개선할 점이 있다면 의견을 남겨주셔도 좋겠습니다.


댓글 (0)

로그인 후 댓글을 남길 수 있습니다.
아직 댓글이 없습니다. 첫 번째 댓글을 남겨보세요!