> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# fpdf2 SVG 이미지: Python PDF에 경로 유지하기

> fpdf2로 Python PDF에 SVG 로고를 배치하고 크기를 제어하세요. 저장된 경로를 확인하고 래스터 대안을 쓰기 전에 누락된 텍스트나 도형을 진단합니다.

Source: https://perfectvector.com/ko/blog/fpdf2-svg-image

Language: ko
Author: Irene Kim
Published: 2026-09-29T08:00:00+09:00

`pdf.image("logo.svg", x=20, y=20, w=60)`으로 fpdf2 문서에 SVG를 배치하세요. 지원되는 SVG 도형은 PDF 그리기 경로가 됩니다. 먼저 로고를 PNG로 렌더링할 필요는 없습니다. 공식 [SVG 문서](https://py-pdf.github.io/fpdf2/SVG.html)는 이 직접 처리 방식과 한계를 설명합니다.

형식 자체가 낯설다면 [SVG 파일 가이드](https://perfectvector.com/ko/blog/what-is-an-svg-file)가 경로와 이미지 컨테이너를 설명합니다. 가져오기에 성공해도 확인이 필요합니다. 파일에 픽셀이 삽입되어 있거나 가져오기 도구가 재현하지 못하는 기능에 의존하거나 그림 주변에 여백이 있을 수 있습니다. 이 가이드는 직접 만든 작은 로고를 명시적 크기로 배치하고 결과 PDF를 검사합니다. 기존 벡터 원본이 있다면 유지하세요. PNG나 JPG에서 그림을 복원하는 것은 별도의 앞 단계입니다.

## 알려진 SVG와 고정된 fpdf2 버전으로 시작하기

Python 3.12와 **fpdf2 2.8.8**로 예제를 실행했습니다. 이는 테스트한 버전이며 모든 이후 릴리스가 똑같이 동작한다는 보장은 아닙니다. 패키지의 [공식 PyPI 페이지](https://pypi.org/project/fpdf2/)는 `fpdf2` 배포 이름으로 설치한다고 설명하며 Python import는 `fpdf`입니다.

다른 프로젝트 패키지와 독립적인 예제가 되도록 새 환경을 사용하세요.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "fpdf2==2.8.8"
```

Windows에서는 대신 `.venv\Scripts\activate`로 환경을 활성화하세요. 이 직접 만든 직사각형 문양을 `logo.svg`로 저장하세요.

```svg
<svg xmlns="http://www.w3.org/2000/svg"
     width="120" height="80" viewBox="0 0 120 80">
  <path fill="#137d89" fill-rule="evenodd"
        d="M10 10H110V70H10Z M30 25H90V55H30Z"/>
</svg>
```

닫힌 하위 경로가 두 개 있습니다. 바깥 사각형은 채워지고 안쪽 사각형은 `evenodd` 채우기 규칙으로 구멍이 됩니다. 글꼴, 이미지나 효과가 없어 첫 테스트를 진단하기 쉽습니다.

다음을 SVG 옆에 `place_logo.py`로 저장하세요.

```python
from pathlib import Path
from fpdf import FPDF

folder = Path(__file__).resolve().parent
pdf = FPDF(unit="mm")
pdf.add_page()
pdf.image(str(folder / "logo.svg"), x=20, y=20, w=60)
pdf.output(str(folder / "logo.pdf"))
```

`python place_logo.py`를 실행하세요. `logo.pdf`를 열고 왼쪽 위 가까이에 중앙으로 페이지가 비치는 청록색 직사각형 프레임이 있는지 확인하세요.

## SVG 캔버스와 칠해진 로고 구분하기

원본 캔버스는 너비 120단위, 높이 80단위의 3:2 비율입니다. `w=60`에서 이 예제는 **60 × 40 mm 캔버스**를 차지합니다. 그림은 원본 좌표 기준으로 캔버스 가장자리에서 10단위 안쪽에 시작하므로 칠해진 바깥 사각형은 **50 × 30 mm**이며 페이지의 **25, 25 mm**에서 시작합니다. 이 예제의 좌표와 배율로 계산한 값입니다.

이 여백 때문에 색칠된 모양의 측정값과 배치 캔버스의 측정값이 다릅니다. 고객 로고가 너무 작아 보이면 PDF 너비를 늘리기 전에 원본 여백을 확인하세요.

[fpdf2 이미지 가이드](https://py-pdf.github.io/fpdf2/Images.html)는 크기 처리와 지정한 상자 안에서 비율을 유지하는 옵션을 설명합니다. 첫 예제에서는 너비만 설정하세요. 나중에 두 크기를 모두 지정한다면 모든 원본이 같은 비율이라고 가정하지 말고 원하는 맞춤을 의도적으로 테스트하세요.

![더 큰 캔버스 안의 직사각형 로고를 문서 페이지에 배치하는 일러스트](https://perfectvector.com/blog/fpdf2-svg-image/canvas-and-paths.webp)

*배치 캔버스에는 그림 주변 여백이 포함됩니다. 이 일러스트는 두 경계를 설명합니다. 실제 크기는 내보낸 PDF를 검사해 검증하세요.*

## 저장된 PDF에 경로가 있는지 검증하기

PDF 미리보기는 모양을 보여 주지만 이미지도 적당한 확대에서는 선명할 수 있습니다. 파일도 검사하세요. **pypdf 6.1.1**로 독립 예제를 검사했습니다.

```bash
python -m pip install "pypdf==6.1.1"
```

```python
from pathlib import Path
from pypdf import PdfReader

folder = Path(__file__).resolve().parent
page = PdfReader(folder / "logo.pdf").pages[0]
print("Page images:", len(page.images))
print(page.get_contents().get_data().decode("latin-1"))
```

출력은 **페이지 이미지 0개**를 보고했습니다. 디코딩한 콘텐츠에는 이동, 직선, 경로 닫기 연산으로 표현한 사각형 윤곽선과 그 뒤의 even-odd 채우기 연산 `f*`가 있었습니다. 렌더링된 구멍과 함께 보면 이 이미지 없는 예제가 저장된 PDF에서도 그리기 도형으로 유지됐다는 결론을 뒷받침합니다.

확인하지 않고 다른 입력에 이 결론을 적용하지 마세요. 보고서의 다른 곳에는 사진이 있어도 되고 SVG 자체에도 이미지가 있을 수 있습니다. [삽입 래스터 진단](https://perfectvector.com/ko/blog/svg-contains-raster-image)은 경로 로고와 SVG 마크업으로 감싼 비트맵을 구분하는 데 도움이 됩니다. 더 복잡한 PDF는 참조 객체 안에 그리기 콘텐츠를 둘 수도 있으므로 위 짧은 스크립트는 독립 예제의 시작점이며 범용 PDF 감사 도구가 아닙니다.

## 설치한 릴리스로 누락된 그림 진단하기

먼저 위 작은 문양을 실행하세요. 예제는 작동하지만 운영 로고는 실패한다면 원본 그림이나 사용하는 기능으로 문제를 좁힌 것입니다. 원본을 보관하고 사본에서 기능 하나씩 단순화하세요.

| 증상                     | 먼저 확인할 사항              | 유용한 다음 단계                         |
| ---------------------- | ---------------------- | --------------------------------- |
| 페이지가 비어 있음             | 파일 경로, 배치, 크기와 가져오기 경고 | 명시적 좌표에서 단순 문양 테스트                |
| 로고가 너무 작아 보임           | 원본 캔버스 안의 여백           | 칠해진 경계와 viewBox 비교                |
| 중앙이 채워짐                | 복합 경로 구조와 채우기 규칙       | 편집·내보내기에서 구멍 유지                   |
| 글자가 없거나 다름             | 설치 릴리스, 글꼴 선택과 텍스트 기능  | 별도 텍스트 예제 테스트 또는 승인된 윤곽선 로고 글자 사용 |
| 장식이 사라짐                | 지원하지 않는 SVG 기능         | 사본에서 해당 기능 제거 후 결과 비교             |
| PDF는 선명하지만 픽셀이 있을 수 있음 | 원본과 PDF의 삽입 이미지        | 미리보기뿐 아니라 파일 구조 검사                |

여기서는 오래된 답변에 주의해야 합니다. 간단한 `<text>` 요소가 있는 별도 2.8.8 테스트는 추출 가능한 `HELLO` 텍스트를 만들었고, 기본 선형 그라디언트 사각형도 성공적으로 내보냈습니다. 이 좁은 검사가 SVG 텍스트, 글꼴, CSS나 그라디언트의 완전한 호환성을 입증하지는 않습니다. 다만 모든 SVG 텍스트나 모든 그라디언트가 지원되지 않는다는 오래된 설명이 불필요한 래스터화를 유도할 수 있음을 보여 줍니다.

현재 [SVG 기능 목록](https://py-pdf.github.io/fpdf2/SVG.html#currently-unsupported-notable-svg-features)에도 마커, 패턴, 경로 위 텍스트와 복잡한 또는 외부 CSS 같은 제한이 있습니다. 진단할 때 가져오기 경고를 보이게 유지하고 저장한 페이지를 원본과 비교하세요. 깨끗한 로그만으로 모든 시각 기능이 유지됐다는 증거가 되지는 않습니다.

## 결과에 맞게 래스터 대안 사용하기

선택한 처리 과정에서 효과를 재현할 수 없다면 모양 유지가 도형 유지보다 중요한지 결정하세요. 해당 문서 부분에는 렌더링한 PNG가 적합할 수 있습니다. 최종 실제 크기에서 확인하고 출력을 정확히 표시하세요. 래스터 렌더링을 삽입해도 원래 경로는 보존되지 않습니다.

브랜드 로고에는 승인된 윤곽선 글자나 더 단순한 벡터 내보내기가 더 나을 수 있습니다. 편집 가능한 문서 텍스트는 문서 작업 흐름에서 글꼴과 텍스트를 처리하세요. 문장 스크린샷을 추적해도 타이포그래피가 복원되거나 선택 가능한 텍스트가 되지는 않습니다.

기존 PDF 코드가 다른 Python 라이브러리를 쓴다면 [ReportLab SVG 작업 흐름](https://perfectvector.com/ko/blog/reportlab-svg)에는 고유한 가져오기·크기 검사가 있습니다. 라이브러리 전환은 별도의 구현 결정이므로 문서를 다시 만들기 전에 실제 문제 기능을 테스트하세요.

## PDF 단계 전에 래스터 원본 그림 준비하기

PNG나 JPG 로고만 남았다면 PerfectVector의 [로고 벡터화 도구](https://perfectvector.com/ko/vectorize-logo)로 fpdf2 가져오기 전 SVG 후보를 준비할 수 있습니다. 윤곽선, 작은 구멍과 색상 영역을 원본과 비교한 뒤 후보에 같은 배치·PDF 검사를 수행하세요.

벡터 원본이 있으면 사용하세요. 정확한 브랜드 글자는 재입력이나 수동 수정이 필요할 수 있습니다. [로고 벡터화 가이드](https://perfectvector.com/ko/blog/how-to-vectorize-a-logo)가 그 선택을 설명합니다. 이 글의 문양은 직접 작성한 SVG이며 측정한 PerfectVector 변환 결과가 아닙니다. PerfectVector는 그림을 준비하고 fpdf2는 PDF 배치를 제어합니다.

## FAQ

**fpdf2가 SVG를 직접 삽입할 수 있나요?**
네. image 메서드에 SVG 파일을 전달하고 위치와 크기를 설정하세요. 지원 도형은 PDF 경로가 될 수 있지만 자신의 그림에서는 내보낸 파일과 모양을 확인하세요.

**fpdf2는 SVG 텍스트를 지원하나요?**
기본 텍스트 테스트는 fpdf2 2.8.8에서 작동했습니다. 모든 글꼴, 레이아웃 기능이나 경로 위 텍스트를 보장하지는 않습니다. 설치 릴리스를 확인하고 실제 문서에서 쓰는 글자를 테스트하세요.

**60 mm 이미지가 60 mm보다 좁아 보이는 이유는 무엇인가요?**
요청한 크기는 배치 캔버스에 적용됩니다. SVG 내부 여백도 캔버스에 포함되므로 칠해진 모양은 더 좁을 수 있습니다.

**PNG 로고를 추가하기 전에 SVG로 변환해야 하나요?**
편집 가능한 경로가 필요하고 그림이 추적에 적합한 경우에만 하세요. 사진은 래스터로 유지하고 원본 벡터 로고가 있으면 사용하세요. 추적 후보를 확인한 뒤 삽입하세요.

## Sources

1. [fpdf2 — SVG](https://py-pdf.github.io/fpdf2/SVG.html) — 직접 SVG 삽입, 기능 지원과 경고 로그를 설명합니다.
2. [fpdf2 — 이미지](https://py-pdf.github.io/fpdf2/Images.html) — 이미지 배치, 크기와 가로세로 비율 맞춤을 설명합니다.
3. [fpdf2 — PyPI 패키지](https://pypi.org/project/fpdf2/) — 설치 가능한 배포 이름과 Python import 규칙을 설명합니다.

***

래스터 로고만 있나요? [PerfectVector로 SVG 후보를 준비](https://perfectvector.com/ko/vectorize-logo)하고 윤곽선과 구멍을 확인하세요. fpdf2로 필요한 크기에 배치한 뒤 저장된 PDF를 검사하세요.

## Explore

- [Read the HTML article](https://perfectvector.com/ko/blog/fpdf2-svg-image)
- [PDFKit SVG: 평면화 없이 벡터 로고 배치하기](https://perfectvector.com/ko/blog/pdfkit-svg.md)
- [CairoSVG: SVG를 올바른 크기의 PDF와 PNG로 내보내기](https://perfectvector.com/ko/blog/cairosvg-output-size.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
