python-docx 사용법, 빈 문서보다 스타일이 든 틀부터
python-docx는 워드의 .docx 파일을 읽고 문단·표를 만드는 파이썬 라이브러리다. Document()에 경로를 주면 그 문서를 열고, 생략하면 라이브러리의 기본 틀을 연다. 그래서 평소 쓰는 보고서 양식과 닮은 틀을 매번 코드로 다시 그릴 필요는 없다. 연습용 문서에서 여백과 제목, 본문 스타일을 만든 뒤 그 파일을 시작점으로 삼을 수 있다.
템플릿(내용을 채우기 전의 문서 틀)에 남겨 둘 것은 제목의 크기, 본문 문단 간격, 표 테두리와 열 너비다. 데이터에는 보고 기간, 요약 문장, 업무 항목만 둔다. 작성자가 바뀔 때마다 글자 크기를 코드에서 다르게 지정하는 일을 줄이려는 구성이다. 내용이 길어지면 줄바꿈과 쪽수는 달라질 수 있으므로, 같은 서식과 같은 쪽수를 구별해서 생각해야 한다.
스타일은 글자와 문단 모양에 붙인 이름이다. 워드의 스타일 목록에 보이는 항목이 시작 문서 안에 실제로 정의되어 있는지도 봐야 한다. 공식 문서는 파이썬으로 사용할 스타일 정의가 시작 문서에 있어야 한다고 설명한다. 워드에서 그 스타일을 적용한 내용을 지워도 정의는 저장된 파일에 남는다. 연습용 본문에 원하는 스타일을 적용해 저장하는 과정이 틀을 준비하는 단계가 된다.
한글 워드 화면과 코드의 이름이 다른 경우도 있다. 내장 제목 스타일은 파일 안에서 Heading 1처럼 영문 이름으로 저장된다. 사용자 지정 스타일은 화면에 붙인 이름 그대로 접근한다. 화면에서 본 이름을 그대로 입력했는데 코드에서 찾지 못한다면 문서에 들어 있는 스타일 목록부터 출력해 보는 편이 빠르다.
문서 파일과 파이썬 환경 준비하기
2026년 11월 12일 조회 기준 PyPI(파이썬 라이브러리를 내려받는 공개 저장소) 최신 배포판은 python-docx 1.2.0, docxtpl 0.20.2다. python-docx의 Python 조건은 3.9 이상이며, 버전 태그의 설정 파일에도 같은 조건이 있다. docxtpl 자체의 조건만 보고 더 낮은 Python을 고르면 함께 쓸 python-docx 조건을 놓칠 수 있다. 아래 명령은 독자의 연습 환경에 해당 버전을 준비하는 예시다.
python --version
python -m pip install python-docx==1.2.0 docxtpl==0.20.2
python -m pip show python-docx docxtpl- 빈 연습 폴더를 만들고 워드에서 새 문서를 연다. 잘 됐으면 본문에 글을 넣을 수 있는 빈 문서가 보인다. 기존 업무 파일을 덮어쓰지 않도록 새 이름으로 시작한다.
- 제목과 본문에 스타일을 적용한 뒤
report-template.docx로 저장한다. 잘 됐으면 폴더 목록에 그 이름이 나타난다. 확장자가 숨겨진 환경에서는 이름 뒤에 확장자를 중복해 붙이지 않았는지 살핀다. - 아래 코드를
inspect_styles.py로 저장하고 같은 폴더에서 실행한다. 잘 됐으면 제목 스타일과 본문 스타일 이름이 출력된다. 파일을 못 찾는다는 오류가 나면 실행 위치와 문서 위치를 먼저 맞춘다.
from docx import Document
from docx.enum.style import WD_STYLE_TYPE
document = Document("report-template.docx")
for style in document.styles:
if style.type == WD_STYLE_TYPE.PARAGRAPH:
print(style.name)python inspect_styles.py이 코드는 스타일 이름을 읽는 예시라 문서 내용이나 서식을 바꾸지 않는다. 제목을 추가하려는 문서에 Heading 1이 없다면 워드에서 제목 스타일을 적용해 저장한 뒤 목록을 다시 본다. 목록에 없는 이름을 코드에서 반복해서 바꾸기보다 시작 문서에 무엇이 들어 있는지를 먼저 보는 순서다.
처음에는 제목·본문·업무 표만 있는 틀로 시작한다. 제목과 본문은 스타일을 적용해 저장하고, 결과 파일은 템플릿과 다른 이름으로 만든다. 문서 경로를 받는 Document와 별도 경로로 저장하는 save가 이 흐름의 기본이다.
보고서에 넣을 수치가 엑셀에서 온다면 클로드로 엑셀·CSV 분석하기의 분석 단계와 문서 편집 단계를 나눠 볼 수 있다. 이 글의 예시는 계산을 맡기지 않고 이미 정한 가상 문자열만 문서에 넣는다.
python-docx 사용법, 문단 전체 교체가 서식을 지우는 자리
워드 문단 안에는 run(같은 글자 서식을 가진 텍스트 조각)이 들어 있다. 제목 문단의 일부만 굵게 만들면 문단 전체 스타일과 부분 글자 서식이 함께 존재한다. 문단의 텍스트를 읽을 때는 이어진 문자열로 보여도, 바꾸는 방법에 따라 조각이 유지되거나 새로 만들어진다. 자리표시자(나중에 값으로 바꿀 표시)를 찾았다고 곧바로 문단 전체를 덮어쓰면 이 차이가 드러난다.
python-docx 1.2.0의 paragraph.text 대입은 내부에서 clear() 뒤 add_run(text)를 호출한다. 문단 스타일은 보존하지만 기존 글자 조각을 비우고 새 조각으로 바꾼다. 그래서 제목 모양은 남는데 문장 가운데 강조한 굵은 글씨가 사라질 수 있다. 파일 저장이 실패한 것과는 다른 문제다.
이 동작은 오류를 숨긴 추측이 아니라 소스 설명에 적힌 계약이다. text 속성에 값을 넣으면 기존 내용을 단일 run으로 교체하고, 굵게·기울임 같은 run 수준 서식을 제거한다고 적혀 있다. 보고서 서식을 지키려면 문단 스타일만 같으면 충분한지, 부분 강조도 남아야 하는지부터 정해야 한다.
글자 조각만 바꾸는 방법에도 조건이 있다
특정 run의 text를 바꾸면 그 run의 서식은 유지된다. 다만 paragraph.runs를 돌며 각 조각에서 표시를 찾는 방법은 표시가 한 조각 안에 들어 있을 때만 단순하게 적용된다. 화면에 붙어 보이는 표시가 내부에서도 한 조각이라는 보장은 없다. 문서 편집 중 일부 글자의 서식을 바꾸면 조각이 나뉠 수 있다는 설명이 docxtpl 문서에도 있다.
예를 들어 보고 기간을 나타내는 표시의 앞부분과 뒷부분이 서로 다른 run에 있으면, 각 run에 대한 문자열 치환으로는 전체 표시를 찾지 못한다. 반대로 문단 전체를 이어 붙여 치환하면 원래 조각별 서식을 다시 배치하는 문제가 생긴다. 일반 문자열 치환을 복잡한 워드 템플릿의 범용 교체법으로 삼기에는 이렇게 조건이 많다.
이 글에서는 워드에서 배치를 정하고 태그를 읽어 값을 넣는 docxtpl을 사용한다. python-docx는 스타일을 읽거나 문서를 구성하는 역할에, docxtpl은 템플릿의 표시를 채우는 역할에 둔다. docxtpl도 내부적으로 python-docx와 Jinja를 사용한다고 공식 안내가 설명한다. Jinja는 표시와 반복문을 해석하는 템플릿 도구다.
표시는 통째로 입력하고, 표시 안의 일부 글자만 굵게 바꾸는 편집은 피한다. 일반 태그는 같은 문단의 같은 run 안에서 사용한다는 문서 제약을 기준으로 틀을 만든다. 특정 편집에서 우연히 나뉜 태그가 처리되더라도 모든 분할 형태가 지원된다는 뜻으로 넓히지 않는다. 표시 자체의 장식보다 표시 주변 문단의 스타일로 모양을 잡으면 관리할 부분이 줄어든다.
| 고치려는 대상 | 사용할 자리 | 주의할 점 |
|---|---|---|
| 제목·본문의 공통 모양 | 워드의 문단 스타일 | 시작 문서에 정의를 남긴다. |
| 단순한 글자 조각 | run.text | 조각의 서식은 남지만 표시가 조각 밖으로 이어질 수 있다. |
| 문단 전체 내용 | paragraph.text | 부분 굵게·기울임은 제거된다. |
| 값과 반복 항목 | docxtpl 태그 | 문단·행을 다루는 특수 태그의 자리를 지킨다. |
틀을 고칠 때의 기준은 한 줄이면 된다. 제목 색을 바꿀 때는 워드에서 제목 스타일을 고치고, 업무 결과를 바꿀 때는 파이썬 쪽 입력값만 고친다. document.paragraphs[3]처럼 문단 번호로 자리를 찾는 코드는 틀에 문단 하나만 끼워 넣어도 엉뚱한 문단을 바꾸므로, 태그 이름으로 자리를 찾는 쪽이 덜 흔들린다. 이것은 이 글에서 제안하는 관리 방식이며, 라이브러리가 변경 이력을 관리해 준다는 뜻은 아니다.
파일이 만들어졌다는 사실과 열었을 때 원하는 결과가 남았다는 사실을 나누는 관점은 openpyxl 파일의 조용한 손상 사례에서도 이어진다. 여기서는 그 기준을 문단과 글자 조각에 적용한다.
인용 — python-docx v1.2.0 소스All run-level formatting, such as bold or italic, is removed.
우리말 뜻: 굵게나 기울임처럼 글자 조각에 적용된 서식은 모두 제거된다. paragraph.text에 값을 대입하는 동작을 설명한 문장이다.
docx 템플릿 파이썬, 표 반복 태그는 행을 나눠 둔다
먼저 report-template.docx의 본문에 아래 표시를 넣는다. 코드는 워드 파일 안에 적을 내용의 본보기다. 코드 블록 자체를 문서에 넣는 것이 아니라, 중괄호를 포함한 표시 문자열을 해당 문단에 입력한다. 각 표시 앞뒤에는 문서가 권하는 공백을 둔다.
{{ report_title }}
보고 기간: {{ period }}
{{ summary }}제목 표시는 제목 문단에, 기간은 본문 문단에, 요약은 별도 문단에 둔다. 일반 문자열 변수는 현재 스타일을 유지하며 값으로 바뀐다는 것이 공식 안내다. 그러므로 제목 전체 표시를 제목 스타일로 꾸미면, 보고서 이름이 바뀔 때마다 파이썬에서 제목 글꼴을 다시 지정할 필요가 줄어든다. 이 설명은 일반 문자열 변수에 대한 것이며 특수한 서식 객체까지 같은 규칙으로 다루지는 않는다.
업무 항목을 반복할 때는 표 안에서 행을 늘리는 전용 태그를 쓴다. 시작 태그, 반복할 본문, 끝 태그를 같은 행에 몰아넣지 않는다. 문서는 {%tr ... %}가 들어 있는 행을 결과에서 제거한다고 설명한다. 반복 조건을 적은 행을 출력할 데이터 행과 분리해야 하는 이유다.
워드 표에 넣을 내용과 기대할 결과
아래 표는 워드에서 만들 표의 배치도다. 머리글은 일반 행으로 두고, 시작 태그 행의 첫 셀에 반복 시작문을 넣는다. 다음 행에는 업무 항목 표시를, 그 아래 행의 첫 셀에는 종료문을 둔다. 제어 행의 나머지 셀은 비워 둔다.
| 업무 | 결과 | 메모 |
|---|---|---|
| {%tr for item in items %} | ||
| {{ item.task }} | {{ item.result }} | {{ item.note }} |
| {%tr endfor %} |
- 머리글 아래에 시작 태그 행을 만든다. 잘 됐으면 첫 셀에
{%tr for item in items %}가 보인다. 철자나 공백이 달라지지 않도록 표시 전체를 입력한다. - 그다음 행에
item.task,item.result,item.note표시를 넣는다. 잘 됐으면 업무·결과·메모 열의 모양이 정해져 있다. 이 행을 워드에서 꾸미고 제어 행은 비워 둔다. - 별도 행에
{%tr endfor %}를 넣고 저장한다. 렌더링(표시를 실제 값으로 바꾸는 처리) 뒤에는 제어 행이 사라지고 items의 항목에 맞는 업무 행이 남는 형태를 기대한다.
표 안에서 일반 {% for ... %}로 여러 행을 가로지르는 대신 전용 태그를 쓰는 것이 문서의 제약에 맞는다. 같은 행에 {%tr를 중복해서 넣는 것도 피해야 한다. 결과에 태그가 그대로 남거나 행이 통째로 빠져 행 반복이 안 되면, 데이터를 바꾸기 전에 태그가 어느 행에 있는지부터 본다. 내용을 넣는 행과 제어 행이 섞여 있으면 서식을 손봐도 반복 구조가 바로잡히지 않는다.
열 너비는 고정해도 긴 본문은 줄을 늘린다. python-docx의 autofit=False는 고정 레이아웃을 뜻하지만, 열 너비 합계가 페이지 폭을 넘으면 어느 설정에서도 폭이 조정될 수 있다고 소스가 적는다. 고정 표라는 말만 믿기보다 워드의 여백 안에 표가 들어가는지 살펴야 한다. 긴 업무명과 메모를 넣는 비교가 필요한 까닭이다.
표의 모양이 잡히면 짧은 항목, 줄이 접히는 긴 항목, 빈 목록으로 결과를 비교한다. 빈 목록일 때 본문 행을 생략할지 안내 문구를 둘지는 보고서 규칙으로 먼저 정한다. 이 글의 표는 반복할 데이터가 없으면 머리글만 남도록 설계한 예시다.
반복 행은 items 목록의 항목 수만큼 늘어날 뿐, 그 안의 값이 맞는지는 따지지 않는다. 진행률처럼 계산이 필요한 값은 파이썬에서 먼저 계산한 뒤 item.result에 들어갈 완성된 문장으로 넘기는 편이 낫다. 템플릿 안에서 계산까지 하면 결과가 다를 때 원인이 서식인지 계산인지 가리기 어렵다.
워드 보고서 자동화, 특수문자와 빠진 값을 저장 전에 잡기
표시 이름이 맞아도 입력값 때문에 결과가 달라질 수 있다. docxtpl의 render는 XML 이스케이프(특수문자를 문서 구조와 섞이지 않게 바꾸는 처리)를 기본으로 켜지 않는다. 버전 0.20.2 소스의 기본 인수는 autoescape=False다. 업무 문장에 &, <, >가 들어갈 수 있으므로 예시에서는 autoescape=True를 명시한다.
빠진 값은 별도 문제다. Jinja의 기본 Undefined는 미정의 값을 출력하거나 반복할 수 있지만, StrictUndefined는 출력·반복·참거짓 검사 등을 오류로 처리한다. 이스케이프는 글자를 올바른 구조로 담는 설정이고, 엄격한 미정의 처리는 입력 누락을 드러내는 설정이다. 어느 하나가 다른 문제까지 검사해 주지는 않는다.
docxtpl의 get_undeclared_template_variables(context=...)는 템플릿이 요구한 최상위 이름에서 제공한 키를 뺀 집합을 돌려준다. 이 비교만으로 items 안의 모든 업무 항목에 result가 있는지까지 알 수는 없다. 목록 안쪽의 빠진 값은 렌더링 때 StrictUndefined로 잡는 구성을 함께 둔다. 값이 존재하지만 빈 문자열인 경우는 미정의가 아니므로 별도의 업무 규칙도 필요하다.
가상 데이터로 결과 파일 만들기
다음 코드를 같은 폴더에 render_report.py로 저장한다. 업무명과 기간은 모두 연습용 문자열이다. 경로와 파일 이름도 예시에서 정한 값이다. 코드의 호출 방식은 공식 문서와 소스를 조합했으며, 이 글에서 워드로 실행·열람한 결과를 주장하지 않는다.
from pathlib import Path
from docxtpl import DocxTemplate
from jinja2 import Environment, StrictUndefined
template_path = Path("report-template.docx")
output_path = Path("report-demo.docx")
if output_path.exists():
raise FileExistsError("report-demo.docx의 이름을 바꾸고 다시 실행한다.")
context = {
"report_title": "가상 업무 보고서",
"period": "연습 기간",
"summary": "A & B 항목의 준비 상황을 정리한다.",
"items": [
{"task": "자료 정리", "result": "초안 준비", "note": "검토 대기"},
{"task": "서식 점검", "result": "틀 비교", "note": "긴 문장도 넣어 본다."},
],
}
if not context["report_title"].strip():
raise ValueError("보고서 제목이 비어 있다.")
template = DocxTemplate(template_path)
environment = Environment(undefined=StrictUndefined, autoescape=True)
missing = template.get_undeclared_template_variables(
jinja_env=environment, context=context
)
if missing:
raise ValueError("빠진 입력: " + ", ".join(sorted(missing)))
template.render(context, jinja_env=environment, autoescape=True)
template.save(output_path)
print(output_path.name)python render_report.py잘 됐으면 터미널에 report-demo.docx가 표시되고 같은 폴더에 결과 파일이 생긴다. 이 메시지는 저장 호출 뒤의 경로 출력이다. 원하는 문장이 들어갔는지, 표가 잘렸는지까지 확인한 신호는 아니다. 결과를 워드에서 다시 열고 제목과 표, 특수문자가 들어간 요약을 읽는 과정이 뒤따라야 한다.
UndefinedError 오류가 나면 템플릿의 표시 이름과 context의 키를 대조한다. 특히 item.result 같은 안쪽 표시를 잘못 적었는지 살핀다. 값이 빠졌다는 오류를 없애려고 StrictUndefined를 빼면 미완성 보고서를 저장할 수 있다. 틀의 표시가 잘못됐는지, 입력에서 필수 항목이 빠졌는지를 고치는 편이 목적에 맞는다.
- 결과 파일을 열어 제목·기간·요약을 읽는다. 잘 됐으면 표시 대신 가상 문자열이 보이고
A & B의 기호도 그대로 남는다. 파일을 열 수 없으면 이스케이프 설정과 입력 문자열부터 본다. - 표의 머리글과 업무 내용을 대조한다. 잘 됐으면 제어 태그 행이 보이지 않고 입력 항목이 본문 행으로 나타난다. 순서가 다르면 context의 items 순서와 템플릿 반복 범위를 함께 본다.
- 메모를 긴 문장으로 바꾼 새 결과를 별도 이름으로 만든다. 잘 됐으면 줄이 늘어도 표가 본문 폭 안에 있고 강조와 제목 스타일이 남는다. 표가 밀리면 열 너비 합계와 문단의 쪽 배치 설정을 살핀다.
문단의 keep_with_next는 다음 문단과 같은 쪽에 두는 성질이고, keep_together는 문단이 쪽 경계에서 나뉘는 것을 다룬다. 제목만 앞쪽 끝에 남는 문제가 있다면 공백 줄을 추가하기보다 제목 스타일의 문단 설정을 살필 수 있다. 이 설정도 데이터 길이를 고정하지는 않으므로 모든 보고서가 같은 쪽수로 나온다는 약속으로 읽지 않는다.
출력 근거를 남길 때는 파일이 있다는 상태와 실제로 열어 읽었다는 상태를 따로 적는다. 이 구별은 공개 샘플에서 구현과 실행 근거를 나누는 방법과도 이어진다. 보고서에서는 저장한 파일 이름, 사용한 틀, 눈으로 비교한 항목을 함께 적어 두면 틀이 바뀐 뒤 차이를 찾기 쉽다.
자주 묻는 것
python-docx만으로 보고서 템플릿을 만들 수 있나?
가능하다. 시작 문서를 열어 문단·표를 추가하고 다른 경로로 저장할 수 있다. 다만 기존 문장 안의 표시를 바꾸며 글자 서식까지 유지하는 일은 교체 범위를 정해야 한다. 문단 전체 대입은 부분 글자 서식을 지우므로, 워드에서 만든 표시와 반복 표를 채울 때는 docxtpl을 조합하는 흐름이 편리하다.
한글 워드에서 보이는 제목 스타일 이름을 코드에 써도 되나?
내장 스타일은 영문 이름으로 조회한다. 사용자 지정 스타일은 직접 붙인 이름을 그대로 쓴다. Heading 1을 찾지 못한다면 시작 문서에 그 스타일 정의가 있는지 출력 목록을 본다. 워드에서 스타일을 적용해 저장하는 과정과 코드에서 그 이름을 조회하는 과정을 나눠 따라가면 된다.
표가 고정 너비인데 결과가 달라지는 이유는 무엇인가?
고정 레이아웃에서도 열 너비 합계가 페이지 폭을 넘으면 조정될 수 있다. 내용이 길어져 줄과 쪽이 늘어나는 일도 따로 본다. 반복 태그 배치가 맞는지 먼저 확인하고, 그다음 표 너비와 문단 배치를 살피면 구조 문제와 배치 문제를 섞지 않고 원인을 좁힐 수 있다.
빈 문자열도 StrictUndefined가 막아 주나?
막지 않는다. StrictUndefined는 정의되지 않은 값의 사용을 엄격하게 다룬다. 키가 있고 값이 빈 문자열이면 미정의 값과 다르다. 예시의 제목 검사처럼 공백뿐인 값을 거절할지, 빈 업무 목록을 허용할지는 보고서의 입력 조건으로 별도 작성해야 한다.
정리 — 틀의 모양과 값의 검사를 함께 남긴다
보고서마다 같은 서식을 쓰려면 워드의 제목·본문·표를 템플릿에 정하고, 파이썬에서는 그 자리에 들어갈 값만 관리하는 흐름부터 만들면 된다. 문단 전체 교체는 부분 글자 서식을 지우며, 반복용 제어 행은 출력할 행과 나눠 두어야 한다. 특수문자 처리와 누락 검사는 각각 명시하고, 저장한 결과는 워드에서 다시 읽는다.
첫 비교에서는 짧은 입력, 긴 입력, 빠진 입력을 나란히 놓으면 충분하다. 제목과 표의 모양이 남았는지, 필수 값이 비었을 때 멈췄는지를 살핀다. 이 비교를 마친 틀을 기준으로 삼아야 내용이 바뀌어서 생긴 차이와 서식이 바뀌어서 생긴 차이를 설명할 수 있다.
참고 자료
- python-docx. PyPI 배포 정보 — 조회 시 최신 버전 1.2.0과 Python 조건(2026-11-12 확인). pypi.org
- docxtpl. PyPI 배포 정보 — 조회 시 최신 버전 0.20.2와 Python 조건(2026-11-12 확인). pypi.org
- python-docx. Working with Styles — 내장 스타일의 영문 이름과 사용자 스타일 이름(2026-11-12 확인). python-docx.readthedocs.io
- python-docx. Understanding Styles — 시작 문서 안의 스타일 정의와 styles.xml(2026-11-12 확인). python-docx.readthedocs.io
- python-docx v1.2.0. paragraph.py — text 대입의 clear와 add_run 호출, 글자 서식 제거(2026-11-12 확인). raw.githubusercontent.com
- python-docx v1.2.0. table.py — autofit 설정과 페이지 폭을 넘는 표의 조정(2026-11-12 확인). raw.githubusercontent.com
- docxtpl. 공식 사용 안내 — 변수·run 제약과 행 반복용 특수 태그(2026-11-12 확인). docxtpl.readthedocs.io
- docxtpl v0.20.2. template.py — autoescape=False 기본값과 미제공 최상위 변수 검사(2026-11-12 확인). raw.githubusercontent.com
- Jinja. API — 기본 Undefined와 StrictUndefined의 차이(2026-11-12 확인). jinja.palletsprojects.com
- python-docx. Document objects — 시작 문서 열기, 표·문단 추가와 별도 파일 저장(2026-11-12 확인). python-docx.readthedocs.io
- python-docx. Text-related objects — run.text의 서식 보존과 문단의 줄·쪽 관련 설정(2026-11-12 확인). python-docx.readthedocs.io
- python-docx v1.2.0. pyproject.toml — Python 3.9 이상 조건과 실제 의존성(2026-11-12 확인). raw.githubusercontent.com
