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

# CairoSVG: exporte PDF e PNG no tamanho certo

> Converta arte SVG com CairoSVG, escolha largura de saída ou escala, entenda DPI e dimensões do contêiner pai e verifique pixels PNG e tamanho da página PDF antes da entrega.

Source: https://perfectvector.com/pt-BR/blog/cairosvg-output-size

Language: pt-BR
Author: Irene Kim
Published: 2026-09-22T08:00:00+09:00
Updated: 2026-09-29T08:00:00+09:00

Use `cairosvg.svg2png()` para uma exportação raster e `cairosvg.svg2pdf()` para um PDF. Para uma largura PNG específica, defina `output_width`; para uma ampliação proporcional, use `scale`. `parent_width` fornece o contêiner usado para resolver dimensões percentuais. `dpi` controla a relação entre pixels e unidades físicas, portanto mudá-lo pode afetar os tamanhos PNG e PDF de formas diferentes.

O exemplo abaixo começa com um pequeno emblema SVG e verifica os arquivos produzidos por cada configuração. Ele atende a designers automatizando exportações de logos e desenvolvedores preparando arte para documentos. O CairoSVG renderiza conteúdo SVG existente. Não traça um logo PNG em traçados editáveis.

## Comece com um SVG autossuficiente

Executamos estes exemplos com Python 3.12.11 e CairoSVG 2.9.1. Instale o conversor com versão fixada em um ambiente do projeto:

```bash
python -m pip install "CairoSVG==2.9.1"
```

O CairoSVG também precisa da biblioteca nativa Cairo. Se a instalação ou importação falhar, siga as notas por sistema operacional em sua [documentação de instalação](https://cairosvg.org/documentation/#installation).

Salve este emblema original de três traçados como `emblem.svg`. A abertura quadrada facilita perceber uma regra de preenchimento ausente, e a barra estreita oferece um ponto de verificação de pequenos detalhes. Esta é arte de demonstração criada manualmente, não uma conversão do PerfectVector.

```xml
<svg xmlns="http://www.w3.org/2000/svg"
     width="240" height="120" viewBox="0 0 240 120">
  <path fill="#176b63" fill-rule="evenodd"
        d="M20 100 V20 H100 V100 Z M40 40 V80 H80 V40 Z"/>
  <path fill="#e5a43a" d="M110 100 L160 20 L210 100 Z"/>
  <path fill="#24435d" d="M220 20 H230 V100 H220 Z"/>
</svg>
```

As dimensões da raiz descrevem a viewport de saída. O `viewBox` descreve o retângulo interno de coordenadas da arte. Aqui, ambos têm a mesma proporção 2:1. Mantenha essa relação deliberada ao adaptar o exemplo ao seu logo.

## Exporte um original no tamanho necessário

Salve isto como `export_emblem.py` ao lado do SVG e execute `python export_emblem.py`:

```python
import cairosvg

cairosvg.svg2png(
    url="emblem.svg",
    write_to="emblem-480.png",
    output_width=480,
)
cairosvg.svg2pdf(
    url="emblem.svg",
    write_to="emblem.pdf",
)
```

Nosso PNG tinha **480 × 240 pixels**. A página PDF tinha **180 × 90 pontos**, equivalentes a **2.5 × 1.25 polegadas**. Essas são medições do exemplo fornecido, não dimensões esperadas de todo SVG.

Os equivalentes por linha de comando são:

```bash
cairosvg emblem.svg --output-width 480 -o emblem-480.png
cairosvg emblem.svg -o emblem.pdf
```

A [referência de API e linha de comando do CairoSVG](https://cairosvg.org/documentation/#python) documenta nomes de arquivo de entrada por `url`, bytes SVG por `bytestring` e saída em arquivo por `write_to`. Na CLI, a extensão do arquivo de saída seleciona o formato.

![Ilustração de um emblema geométrico se dividindo em duas exportações proporcionalmente semelhantes em áreas de desenho de tamanhos diferentes](https://perfectvector.com/blog/cairosvg-output-size/output-sizing.webp)

*Ilustração da decisão de exportação: guarde um original vetorial e escolha as dimensões necessárias para cada entrega. Os resultados medidos do CairoSVG estão listados abaixo.*

## Escolha o controle adequado ao problema

As opções com nomes semelhantes respondem a perguntas diferentes. A [referência de tamanho do CairoSVG](https://cairosvg.org/documentation/#command-line) separa o contêiner pai das dimensões de saída solicitadas.

| Seu requisito                                              | Opção Python                    | Opção CLI             | O que conferir                                             |
| ---------------------------------------------------------- | ------------------------------- | --------------------- | ---------------------------------------------------------- |
| Criar um PNG com exatamente 480 pixels de largura          | `output_width=480`              | `--output-width 480`  | Altura e proporções da arte                                |
| Dobrar as dimensões de saída resolvidas                    | `scale=2`                       | `--scale 2`           | Ambas as dimensões dobradas                                |
| Resolver largura ou altura da raiz expressa em porcentagem | `parent_width`, `parent_height` | `--width`, `--height` | Porcentagem do contêiner fornecido                         |
| Interpretar unidades físicas, como polegadas               | `dpi`                           | `--dpi`               | Dimensões em pixels PNG e tamanho físico PDF separadamente |

Para nosso SVG original dimensionado em pixels, executamos cada opção independentemente:

| Configurações      | Dimensões PNG | Dimensões da página PDF |
| ------------------ | ------------- | ----------------------- |
| Padrões            | 240 × 120 px  | 180 × 90 pt             |
| `output_width=480` | 480 × 240 px  | 360 × 180 pt            |
| `scale=2`          | 480 × 240 px  | 360 × 180 pt            |
| `dpi=192`          | 240 × 120 px  | 90 × 45 pt              |

A última linha é a armadilha: dobrar o DPI não deu mais pixels PNG a este SVG dimensionado em pixels. Fez as mesmas dimensões em pixels ocuparem menos espaço físico no PDF. Use uma dimensão de saída quando o requisito de entrega for uma contagem de pixels.

Fornecer ambas as dimensões de saída define o retângulo da área de desenho; não garante uma caixa ajustada aos limites do logo. As regras de proporção do SVG e qualquer área vazia dentro de seu `viewBox` ainda importam. Comece com uma dimensão de saída quando quiser as proporções originais e inspecione o resultado.

### Dimensões percentuais precisam de um contêiner pai

Para uma cópia do exemplo cuja raiz usa `width="50%" height="50%"`, esta chamada fornece um contêiner pai de 960 × 480 pixels:

```python
cairosvg.svg2png(
    url="emblem-percent.svg",
    parent_width=960,
    parent_height=480,
    write_to="emblem-percent.png",
)
```

Nossa saída tinha 480 × 240 pixels: metade da largura do pai e metade de sua altura. Isso explica por que `parent_width=480` não é intercambiável com `output_width=480`.

Se o CairoSVG informar que o tamanho SVG é indefinido, inspecione primeiro as dimensões da raiz. Dê ao documento dimensões positivas adequadas ao uso ou forneça dimensões do pai quando porcentagens dependerem delas. Não deduza o tamanho pretendido da página pelo tamanho em que um navegador acaba exibindo a arte.

### Dimensões físicas se comportam diferente

Mude a raiz original para `width="2.5in" height="1.25in"`, mantendo seu `viewBox`. Em nosso teste, `dpi=96` produziu um PNG de 240 × 120, e `dpi=192` produziu um de 480 × 240. Ambos os PDFs permaneceram 180 × 90 pontos.

Aqui, o SVG original define um tamanho físico, portanto mais pixels por polegada aumentam a resolução raster preservando o tamanho físico da página PDF. O mesmo princípio permite que uma página criada deliberadamente use milímetros ou polegadas. Confira a caixa de página do PDF exportado em vez de presumir que uma grande quantidade de pixels signifique uma página A4 ou carta.

Se o logo precisar ficar dentro de um relatório com texto, margens e vários elementos, use uma etapa de layout de documento. Nosso [guia de inserção SVG no ReportLab](https://perfectvector.com/pt-BR/blog/reportlab-svg) aborda construção direta de PDF; as [verificações de recursos e tamanho do WeasyPrint](https://perfectvector.com/pt-BR/blog/weasyprint-svg-image-pdf) abordam documentos HTML.

## Verifique a exportação, incluindo o que permaneceu vetorial

Lemos os cabeçalhos PNG com Pillow e as caixas de página e fluxos de conteúdo PDF com pypdf 6.10.0. Cada um dos quatro PDFs gerados a partir do SVG dimensionado em pixels continha operações de traçados de desenho e zero imagens de página. Isso confirma geometria vetorial para este exemplo simples sem imagens. Não estabelece fidelidade completa para qualquer SVG.

Para conferir suas próprias dimensões de saída, instale `pillow` e `pypdf` no mesmo ambiente e execute:

```python
from PIL import Image
from pypdf import PdfReader

with Image.open("emblem-480.png") as image:
    print("PNG pixels:", image.size)

page = PdfReader("emblem.pdf").pages[0]
print("PDF points:", float(page.mediabox.width),
      float(page.mediabox.height))
print("Page images:", len(page.images))
```

A [referência de `PageObject`](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) descreve `mediabox` e `images`. A contagem de imagens é um diagnóstico útil, mas não prova que todas as formas, fontes ou efeitos sobreviveram corretamente.

Antes da entrega:

1. Abra o PNG e o PDF e compare o emblema com o SVG. Confira sua abertura, triângulo, barra e margens.
2. Verifique as dimensões em pixels PNG e as dimensões físicas PDF independentemente.
3. Inspecione a arte no tamanho pretendido de uso, incluindo espaços estreitos e pequenos detalhes.
4. Guarde o SVG original e repita estas verificações após mudá-lo ou atualizar o conversor.

A [página de suporte SVG do CairoSVG](https://cairosvg.org/svg_support/) informa que a saída vetorial é preservada quando possível. Imagens raster incorporadas permanecem conteúdo raster. Se seu arquivo contém um PNG em um invólucro SVG, o [diagnóstico de imagens incorporadas](https://perfectvector.com/pt-BR/blog/svg-contains-raster-image) ajuda a identificá-lo antes de exportar.

O CairoSVG é um renderizador estático. Animação, scripts, layout avançado de texto e muitos filtros ficam fora de seu fluxo compatível. Sua documentação lista apenas `feOffset`, `feBlend` e `feFlood` como filtros suportados. Para arte que depende de outros efeitos, compare o resultado cuidadosamente ou exporte por um aplicativo que suporte esses recursos. Uma chamada de conversão bem-sucedida, sozinha, é insuficiente.

## Recupere um original vetorial apenas quando a imagem original precisar

Se seu logo existe apenas como PNG ou JPG, o PerfectVector pode fornecer a etapa anterior de raster para SVG antes de o CairoSVG exportá-lo. Confira as formas recuperadas, as pequenas aberturas e as letras da marca em um editor e salve um original SVG autossuficiente. Nosso [fluxo de vetorização de logos](https://perfectvector.com/pt-BR/blog/how-to-vectorize-a-logo) explica essa inspeção.

Um SVG editável existente pode seguir direto para a exportação. Convertê-lo em PNG e traçá-lo novamente descartaria geometria útil de origem. Fotos podem permanecer imagens raster quando esse for o conteúdo pretendido.

Para um logo apenas raster, [experimente sua própria imagem no PerfectVector](https://perfectvector.com/pt-BR/vectorize-logo), inspecione os contornos e as aberturas do SVG e verifique as dimensões em pixels e o tamanho físico da página de suas exportações CairoSVG.

## Perguntas frequentes

**Por que mudar o DPI deixa meu PNG do mesmo tamanho?**
Se a raiz SVG usa dimensões em pixels, mudar o DPI não necessariamente muda a contagem de pixels PNG. Neste exemplo, um SVG de 240 por 120 pixels manteve esse tamanho com 192 DPI. Use output\_width ou scale quando precisar de mais pixels de saída.

**Largura do pai é o mesmo que largura de saída?**
Não. parent\_width fornece o contêiner usado para resolver dimensões percentuais. output\_width solicita a largura final de saída. Uma largura de raiz de 50% com parent\_width de 960 resultou em 480 pixels no exemplo.

**O CairoSVG sempre cria um PDF inteiramente vetorial?**
Não. O CairoSVG preserva a saída vetorial quando possível, mas um SVG pode incluir imagens raster e recursos incompatíveis. Inspecione o conteúdo e a aparência do PDF em vez de tratar a extensão do arquivo como prova.

## Fontes

1. [Documentação do CairoSVG](https://cairosvg.org/documentation/) — Descreve instalação, APIs de conversão, controles de tamanho e limitações de renderização.
2. [Suporte SVG 1.1 do CairoSVG](https://cairosvg.org/svg_support/) — Explica preservação vetorial, imagens incorporadas e recursos incompatíveis.
3. [Referência de PageObject do pypdf](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) — Documenta as interfaces de caixa de página e imagem usadas para inspecionar o PDF.

## Explore

- [Read the HTML article](https://perfectvector.com/pt-BR/blog/cairosvg-output-size)
- [Imagens SVG no fpdf2: traçados no PDF em Python](https://perfectvector.com/pt-BR/blog/fpdf2-svg-image.md)
- [SVG no PDFKit: insira um logo vetorial sem achatar](https://perfectvector.com/pt-BR/blog/pdfkit-svg.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
