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

# CairoSVG: exporta SVG a PDF y PNG al tamaño correcto

> Convierte ilustraciones SVG con CairoSVG, elige ancho de salida o escala, entiende DPI y dimensiones del contenedor y verifica píxeles PNG y tamaño de página PDF antes de entregar.

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

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

Usa `cairosvg.svg2png()` para una exportación raster y `cairosvg.svg2pdf()` para un PDF. Para un ancho PNG específico, establece `output_width`; para una ampliación proporcional, utiliza `scale`. `parent_width` proporciona el contenedor utilizado para resolver dimensiones porcentuales. `dpi` controla la relación entre píxeles y unidades físicas, así que cambiarlo puede afectar de forma distinta a los tamaños PNG y PDF.

El ejemplo siguiente empieza con un pequeño emblema SVG y comprueba los archivos producidos por cada ajuste. Sirve para diseñadores que automatizan exportaciones de logotipos y desarrolladores que preparan ilustraciones para documentos. CairoSVG renderiza contenido SVG existente. No vectoriza un logotipo PNG en trazados editables.

## Empieza con un SVG autónomo

Ejecutamos estos ejemplos con Python 3.12.11 y CairoSVG 2.9.1. Instala el conversor con la versión fijada en un entorno de proyecto:

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

CairoSVG también necesita la biblioteca nativa Cairo. Si falla la instalación o importación, sigue las notas para tu sistema operativo de su [documentación de instalación](https://cairosvg.org/documentation/#installation).

Guarda este emblema original de tres trazados como `emblem.svg`. La abertura cuadrada facilita detectar una regla de relleno ausente y la barra estrecha proporciona un punto de comprobación de detalle pequeño. Es una ilustración de demostración creada a mano, no una conversión de 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>
```

Las dimensiones del elemento raíz describen el área de visualización de salida. El `viewBox` describe el rectángulo interno de coordenadas de la ilustración. Aquí ambos tienen la misma proporción 2:1. Mantén esa relación de forma deliberada al adaptar el ejemplo a tu logotipo.

## Exporta un maestro al tamaño necesario

Guarda esto como `export_emblem.py` junto al SVG y ejecuta después `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",
)
```

Nuestro PNG tenía **480 × 240 píxeles**. La página PDF medía **180 × 90 puntos**, equivalentes a **2.5 × 1.25 pulgadas**. Son mediciones del ejemplo suministrado, no dimensiones que debas esperar de todos los SVG.

Los equivalentes de línea de comandos son:

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

La [referencia de API y línea de comandos de CairoSVG](https://cairosvg.org/documentation/#python) documenta nombres de archivo de entrada mediante `url`, bytes SVG mediante `bytestring` y salida a archivo mediante `write_to`. En la CLI, la extensión del nombre de archivo de salida selecciona el formato.

![Ilustración de un emblema geométrico que se divide en dos exportaciones de proporciones similares sobre lienzos de distintos tamaños](https://perfectvector.com/blog/cairosvg-output-size/output-sizing.webp)

*Ilustración de la decisión de exportación: conserva un maestro vectorial y después elige las dimensiones necesarias para cada entrega. Los resultados medidos de CairoSVG aparecen a continuación.*

## Elige el control que corresponda al problema

Las opciones con nombres parecidos responden a preguntas distintas. La [referencia de tamaños de CairoSVG](https://cairosvg.org/documentation/#command-line) separa el contenedor padre de las dimensiones de salida solicitadas.

| Tu necesidad                                                         | Opción Python                   | Opción CLI            | Qué comprobar                                                       |
| -------------------------------------------------------------------- | ------------------------------- | --------------------- | ------------------------------------------------------------------- |
| Crear un PNG de exactamente 480 píxeles de ancho                     | `output_width=480`              | `--output-width 480`  | Altura y proporciones de la ilustración                             |
| Duplicar las dimensiones de salida resueltas                         | `scale=2`                       | `--scale 2`           | Ambas dimensiones duplicadas                                        |
| Resolver ancho o altura del elemento raíz expresados como porcentaje | `parent_width`, `parent_height` | `--width`, `--height` | Porcentaje del contenedor proporcionado                             |
| Interpretar unidades físicas como pulgadas                           | `dpi`                           | `--dpi`               | Dimensiones en píxeles del PNG y tamaño físico del PDF por separado |

Para nuestro original dimensionado en píxeles, ejecutamos cada opción de forma independiente:

| Ajustes            | Dimensiones PNG | Dimensiones de página PDF |
| ------------------ | --------------- | ------------------------- |
| Predeterminados    | 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                |

La última fila es la trampa: duplicar DPI no dio más píxeles PNG a este SVG dimensionado en píxeles. Hizo que las mismas dimensiones en píxeles ocuparan menos espacio físico en el PDF. Utiliza una dimensión de salida cuando tu requisito de entrega sea un número de píxeles.

Proporcionar ambas dimensiones de salida establece el rectángulo del lienzo; no garantiza un cuadro de logotipo completamente ocupado. Las reglas de proporción del SVG y cualquier área vacía dentro de su `viewBox` siguen importando. Empieza con una sola dimensión de salida cuando quieras las proporciones originales y después inspecciona el resultado.

### Las dimensiones porcentuales necesitan un contenedor padre

Para una copia del ejemplo cuyo elemento raíz utilice `width="50%" height="50%"`, esta llamada proporciona un contenedor padre de 960 × 480 píxeles:

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

Nuestra salida tenía 480 × 240 píxeles: la mitad del ancho y la mitad de la altura del contenedor padre. Esto explica por qué `parent_width=480` no es intercambiable con `output_width=480`.

Si CairoSVG indica que el tamaño SVG no está definido, inspecciona primero las dimensiones del elemento raíz. Da al documento dimensiones positivas adecuadas para su uso o proporciona las dimensiones del contenedor padre cuando los porcentajes dependan de ellas. No deduzcas el tamaño de página previsto del tamaño al que un navegador muestre la ilustración.

### Las dimensiones físicas se comportan de otra manera

Cambia el elemento raíz original a `width="2.5in" height="1.25in"`, conservando su `viewBox`. En nuestra prueba, `dpi=96` produjo un PNG de 240 × 120 y `dpi=192` produjo un PNG de 480 × 240. Ambos PDF permanecieron en 180 × 90 puntos.

Aquí el original define un tamaño físico, así que más píxeles por pulgada aumentan la resolución raster mientras conservan el tamaño físico de página PDF. El mismo principio permite que una página creada deliberadamente utilice milímetros o pulgadas. Comprueba el cuadro de página del PDF exportado en lugar de suponer que un gran número de píxeles significa una página A4 o carta.

Si el logotipo debe estar dentro de un informe con texto, márgenes y varios elementos, utiliza un paso de composición de documentos. Nuestra [guía de colocación SVG de ReportLab](https://perfectvector.com/es/blog/reportlab-svg) explica la construcción directa de PDF; las [comprobaciones de recursos y tamaños de WeasyPrint](https://perfectvector.com/es/blog/weasyprint-svg-image-pdf) cubren documentos HTML.

## Verifica la exportación, incluido lo que siguió siendo vectorial

Leímos las cabeceras PNG con Pillow y los cuadros de página y flujos de contenido PDF con pypdf 6.10.0. Cada uno de los cuatro PDF del original dimensionado en píxeles contenía operaciones de trazado de dibujo y cero imágenes de página. Eso confirma geometría vectorial para este ejemplo sencillo sin imágenes. No demuestra fidelidad completa para un SVG arbitrario.

Para comprobar tus propias dimensiones de salida, instala `pillow` y `pypdf` en el mismo entorno y ejecuta:

```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))
```

La [referencia de `PageObject`](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) describe `mediabox` e `images`. El número de imágenes es un diagnóstico útil, pero no puede demostrar que cada forma, fuente o efecto se haya conservado correctamente.

Antes de entregar:

1. Abre el PNG y el PDF y compara el emblema con el SVG. Comprueba su abertura, triángulo, barra y márgenes.
2. Verifica independientemente las dimensiones en píxeles del PNG y las dimensiones físicas del PDF.
3. Inspecciona la ilustración a su tamaño de uso previsto, incluidos huecos estrechos y detalles pequeños.
4. Conserva el SVG original y repite estas comprobaciones después de cambiarlo o actualizar el conversor.

La [página de compatibilidad SVG de CairoSVG](https://cairosvg.org/svg_support/) dice que la salida vectorial se conserva cuando es posible. Las imágenes raster incrustadas siguen siendo contenido raster. Si tu archivo contiene un PNG en un contenedor SVG, el [diagnóstico de imágenes incrustadas](https://perfectvector.com/es/blog/svg-contains-raster-image) te ayuda a identificarlo antes de exportar.

CairoSVG es un renderizador estático. La animación, los scripts, la disposición avanzada de texto y muchos filtros están fuera de su flujo compatible. Su documentación enumera únicamente `feOffset`, `feBlend` y `feFlood` como filtros compatibles. Para ilustraciones que dependan de otros efectos, compara cuidadosamente el resultado o exporta mediante una aplicación que admita esas funciones. Una llamada de conversión correcta por sí sola no basta.

## Recupera un maestro vectorial solo cuando lo necesite el original

Si tu logotipo solo se conserva como PNG o JPG, PerfectVector puede proporcionar el paso previo de raster a SVG antes de que CairoSVG lo exporte. Comprueba las formas recuperadas, las aberturas pequeñas y las letras de marca en un editor y guarda después un maestro SVG autónomo. Nuestro [flujo de vectorización de logotipos](https://perfectvector.com/es/blog/how-to-vectorize-a-logo) explica esa inspección.

Un SVG editable existente puede pasar directamente a la fase de exportación. Convertirlo a PNG y volver a vectorizarlo descartaría geometría de origen útil. Las fotos pueden seguir siendo imágenes raster cuando ese sea el contenido previsto.

Para un logotipo que solo existe como raster, [prueba tu propia imagen en PerfectVector](https://perfectvector.com/es/vectorize-logo), inspecciona los contornos y aberturas del SVG y verifica después tanto las dimensiones en píxeles como el tamaño físico de página de tus exportaciones CairoSVG.

## Preguntas frecuentes

**¿Por qué cambiar DPI deja mi PNG del mismo tamaño?**
Si el elemento raíz SVG utiliza dimensiones en píxeles, cambiar DPI no cambia necesariamente el número de píxeles PNG. En este ejemplo, un SVG de 240 por 120 píxeles conservó ese tamaño a 192 DPI. Usa output\_width o scale cuando necesites más píxeles de salida.

**¿El ancho del contenedor padre es lo mismo que el ancho de salida?**
No. parent\_width proporciona el contenedor utilizado para resolver dimensiones porcentuales. output\_width solicita el ancho de salida final. Un ancho de raíz del 50% con parent\_width de 960 se resolvió en 480 píxeles en el ejemplo.

**¿CairoSVG siempre crea un PDF completamente vectorial?**
No. CairoSVG conserva salida vectorial cuando es posible, pero un SVG puede incluir imágenes raster y funciones incompatibles. Inspecciona el contenido y la apariencia del PDF en lugar de tratar la extensión del archivo como prueba.

## Fuentes

1. [Documentación de CairoSVG](https://cairosvg.org/documentation/) — Describe instalación, API de conversión, controles de tamaño y limitaciones de renderizado.
2. [Compatibilidad SVG 1.1 de CairoSVG](https://cairosvg.org/svg_support/) — Explica conservación vectorial, imágenes incrustadas y funciones incompatibles.
3. [Referencia PageObject de pypdf](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) — Documenta las interfaces de cuadros de página e imágenes utilizadas para inspeccionar el PDF.

## Explore

- [Read the HTML article](https://perfectvector.com/es/blog/cairosvg-output-size)
- [Imágenes SVG en fpdf2: conserva los trazados en tu PDF de Python](https://perfectvector.com/es/blog/fpdf2-svg-image.md)
- [SVG en PDFKit: coloca un logotipo vectorial sin aplanarlo](https://perfectvector.com/es/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)
