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

# SVG in WeasyPrint: correggere i loghi assenti nei PDF

> Correggi i loghi SVG assenti nei PDF WeasyPrint con un URL base corretto e dimensioni CSS esplicite, poi verifica tracciati, proporzioni e grafica nel PDF salvato.

Source: https://perfectvector.com/it/blog/weasyprint-svg-image-pdf

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

WeasyPrint può inserire un SVG in un PDF attraverso un elemento immagine HTML. Se il logo scompare quando passi l'HTML come stringa, controlla prima l'URL dell'immagine: un percorso relativo richiede un URL base. Una volta caricato il file, imposta le dimensioni di stampa in CSS ed esamina il PDF salvato. L'[attuale documentazione API di WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/api_reference.html#weasyprint.HTML) documenta questo requisito di `base_url`.

L'esempio qui sotto riproduce il caso dell'immagine assente con un logo originale a forma di cornice. Verifica anche che il PDF corretto contenga geometria vettoriale alle dimensioni richieste. Se hai già un SVG, parti da quel file. La vettorializzazione entra in questo procedimento soltanto quando la grafica sorgente esiste come pixel.

> **Controlla il caricamento prima di cambiare la grafica**
>
> Un PDF può essere creato anche se manca il logo. Controlla l'avviso sulla risorsa, risolvi il percorso dell'immagine e renderizza di nuovo lo stesso SVG prima di modificarne le forme o convertirlo in un altro formato.

## Riproduci l'SVG assente con un piccolo documento

Abbiamo testato con Python 3.13.9 e WeasyPrint 70.0. Usa un ambiente di progetto e installa la versione fissata:

```bash
python -m pip install "weasyprint==70.0"
python -m weasyprint --info
```

WeasyPrint richiede anche librerie native, tra cui Pango. Segui le sue [istruzioni di installazione per sistema operativo](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation) se l'importazione o il comando della versione non riesce. Una libreria nativa assente è un problema diverso da un logo assente.

Crea questa struttura di cartelle:

```text
example/
  render.py
  assets/
    logo.svg
```

Salva questa grafica dimostrativa originale come `assets/logo.svg`. L'apertura centrale offre qualcosa di più utile da esaminare rispetto a un rettangolo pieno. È geometria scritta a mano, non una conversione PerfectVector.

```xml
<svg xmlns="http://www.w3.org/2000/svg"
     width="120" height="60" viewBox="0 0 120 60">
  <path fill="#087f8c" fill-rule="evenodd"
        d="M0 0H120V60H0Z M20 15V45H100V15Z"/>
</svg>
```

Inserisci quanto segue in `render.py`:

```python
from pathlib import Path
import logging
from weasyprint import HTML

logging.basicConfig(level=logging.WARNING)
root = Path(__file__).resolve().parent

html = """<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    @page { size: A4; margin: 20mm; }
    body { margin: 0; }
    .logo { display: block; width: 60mm; height: auto; }
  </style>
</head>
<body>
  <img class="logo" src="assets/logo.svg" alt="Frame logo">
</body>
</html>
"""

HTML(string=html).write_pdf(root / "missing-base.pdf")

HTML(
    string=html,
    base_url=root.as_uri() + "/",
).write_pdf(root / "resolved.pdf")
```

Esegui `python render.py`. Nel nostro primo PDF la cornice era assente e compariva il testo alternativo dell'immagine. Il log conteneva:

```text
Relative URI reference without a base URI: assets/logo.svg
```

Il secondo PDF mostrava la cornice verde petrolio con l'apertura intatta. Entrambe le chiamate hanno prodotto un file, quindi l'esistenza di un PDF da sola non era un controllo utile della riuscita.

## Dai ai percorsi relativi una cartella iniziale stabile

`assets/logo.svg` identifica un file rispetto a qualcos'altro. Il `base_url` nella seconda chiamata fornisce quel punto di partenza. `root.as_uri()` crea un URI file assoluto; la barra finale lo rende una base di directory. Il logo resta nella stessa cartella `assets` e il contenuto SVG non cambia.

L'uso di `Path(__file__)` mantiene inoltre l'esempio legato alla cartella dello script quando lo avvii da un'altra directory di lavoro. In un notebook usa invece una cartella di progetto esplicita, perché `__file__` normalmente non è disponibile.

![Illustrazione di una grafica SVG in una cartella collegata da una freccia alla stessa grafica su una pagina di documento](https://perfectvector.com/blog/weasyprint-svg-image-pdf/resource-resolution.webp)

*Illustrazione della risoluzione delle risorse: il documento deve avere un percorso verso il file SVG prima di poter inserire la grafica.*

Esiste un altro test di controllo utile. Salva l'HTML come `invoice.html` accanto a `render.py` e carica direttamente il file:

```python
HTML(filename=str(root / "invoice.html")).write_pdf(
    root / "from-file.pdf"
)
```

WeasyPrint può ricavare una base dal nome o dall'URL del file in ingresso. Il nostro test basato su file ha prodotto la stessa cornice del caso con base esplicita. Una stringa HTML non ha un nome di file corrispondente da cui dedurla. Queste modalità di ingresso e le loro regole di risoluzione della base sono documentate nel [costruttore HTML](https://doc.courtbouillon.org/weasyprint/stable/api_reference.html#weasyprint.HTML).

Per un'immagine protetta da autenticazione, un URL corretto può comunque non bastare. La [documentazione del recupero degli URL](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#url-fetchers) dice che il client HTTP predefinito non fornisce cookie né autenticazione. Usa il sistema di recupero delle risorse approvato dalla tua applicazione e testalo nell'ambiente che genera il PDF. Non supporre che un logo visibile nel browser con accesso effettuato sia accessibile al processo PDF.

## Imposta separatamente dimensioni dell'immagine e della pagina PDF

L'esempio usa `@page` per il foglio A4 e i margini, mentre `.logo` imposta l'immagine a 60 mm di larghezza. Le proporzioni sorgente 2:1 la rendono alta 30 mm con `height: auto`. Nel PDF salvato la cornice misurava 60 × 30 mm e iniziava a 20 mm dai bordi superiore e sinistro della pagina.

Qui il disegno occupa tutto il `viewBox`. Il tuo logo può avere spazio vuoto all'interno di quel rettangolo, quindi un riquadro immagine di 60 mm può contenere un marchio visibilmente più stretto. Controlla la tela SVG prima di compensare con una larghezza CSS arbitrariamente maggiore. La [guida alle dimensioni di importazione SVG](https://perfectvector.com/it/blog/svg-imports-wrong-size) spiega questa distinzione più nel dettaglio.

Mantieni `write_pdf()` al valore predefinito `zoom=1` quando controlli le dimensioni fisiche. La [documentazione sull'uscita PDF](https://doc.courtbouillon.org/weasyprint/stable/api_reference.html#weasyprint.HTML.write_pdf) di WeasyPrint avverte che cambiare `zoom` ridimensiona anche le unità CSS fisiche e i formati pagina con nome.

| Cosa vedi                                          | Primo controllo                                | Passaggio successivo                                                          |
| -------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| Il testo alternativo sostituisce il logo           | URL dell'immagine e log delle risorse          | Fornisci un URL base valido o un URL assoluto raggiungibile                   |
| Il logo appare delle dimensioni sbagliate          | Larghezza CSS e proporzioni della sorgente     | Imposta una larghezza fisica ed esamina la tela SVG                           |
| Manca una parte della grafica                      | Limiti della sorgente e funzione SVG specifica | Riduci il caso a un piccolo esempio che fallisce e confronta il PDF esportato |
| Il rendering locale funziona, quello sul server no | File disponibili, font e accesso agli URL      | Testa con le risorse del processo distribuito                                 |

## Esamina contenuto e aspetto del PDF

L'attuale [documentazione dei formati WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/api_reference.html#html) dice che le immagini SVG vengono renderizzate come vettori nell'uscita PDF. Questo non significa che ogni file con estensione `.svg` sia interamente vettoriale: un SVG può contenere una bitmap incorporata. Controllalo con la [diagnosi delle immagini incorporate](https://perfectvector.com/it/blog/svg-contains-raster-image) quando il risultato appare ancora pixelato.

Per questo semplice campione abbiamo esaminato i PDF salvati con PyMuPDF 1.26.7:

| Caso di ingresso                       | Record di disegno | Immagini incorporate | Cornice visibile                        |
| -------------------------------------- | ----------------- | -------------------- | --------------------------------------- |
| Stringa HTML senza base                | 0                 | 0                    | Assente; compariva il testo alternativo |
| Stringa HTML con la cartella come base | 1                 | 0                    | 60 × 30 mm, apertura conservata         |
| HTML caricato tramite nome del file    | 1                 | 0                    | Stesso risultato della stringa risolta  |

Questi risultati riguardano la cornice fornita, non ogni funzione SVG. Un solo tracciato composto non significa neppure una sola forma visibile: il suo sottotracciato interno definisce l'apertura.

Per esaminare il tuo `resolved.pdf`, installa `pymupdf==1.26.7` ed esegui:

```python
import pymupdf

with pymupdf.open("resolved.pdf") as document:
    page = document[0]
    print("Drawing records:", len(page.get_drawings()))
    print("Embedded images:", len(page.get_images()))
    for drawing in page.get_drawings():
        box = drawing["rect"]
        print("Bounds in mm:", box.width * 25.4 / 72,
              box.height * 25.4 / 72)
```

La [documentazione della pagina](https://pymupdf.readthedocs.io/en/latest/page.html) di PyMuPDF descrive i metodi di ispezione di disegni e immagini. Questi conteggi sono strumenti diagnostici, non una certificazione di fedeltà. Apri anche il PDF: controlla l'apertura, i colori, le proporzioni e le eventuali scritte alle dimensioni effettive di consegna. Esamina la grafica complessa funzione per funzione e ripeti i controlli quando aggiorni il renderer.

## Quando preparare prima un nuovo SVG

Quando l'unico logo disponibile è un PNG o JPG, il [vettorializzatore di loghi](https://perfectvector.com/it/vectorize-logo) di PerfectVector può preparare un candidato SVG prima dell'inserimento nel documento HTML. Esamina contorni, piccole aperture e scritte in un editor, poi testa l'SVG attraverso lo stesso processo WeasyPrint. La [guida alla vettorializzazione delle immagini](https://perfectvector.com/it/blog/what-is-image-vectorization) spiega cosa cambia quando i pixel diventano tracciati.

Conserva un SVG originale modificabile quando esiste. Correggine il riferimento al file o l'impaginazione anziché ricalcarlo di nuovo. Le fotografie possono restare immagini raster e le scritte esatte di un marchio possono richiedere il font originale o un ridisegno manuale. La vettorializzazione non corregge file assenti sul server, autenticazione o funzioni di rendering non supportate.

Se devi soltanto convertire un SVG nella propria pagina PDF, il [procedimento di esportazione CairoSVG](https://perfectvector.com/it/blog/cairosvg-output-size) descrive quel lavoro più circoscritto. WeasyPrint è adatto al documento HTML, in cui la grafica condivide la pagina con altri contenuti.

## FAQ

**Perché WeasyPrint crea un PDF senza il mio logo SVG?**
Un errore di caricamento dell'immagine può lasciare renderizzabile il resto del documento. Controlla il log delle risorse e l'URL dell'immagine. Nel test fornito, una stringa HTML con un percorso immagine relativo richiedeva un URL base esplicito.

**Devo prima convertire l'SVG in PNG?**
No. WeasyPrint accetta immagini SVG. Mantieni come SVG la grafica vettoriale supportata quando è l'uscita desiderata e controlla il PDF salvato. Un'esportazione raster è un'alternativa quando scegli deliberatamente l'aspetto rispetto alla geometria vettoriale.

**base\_url cambia le dimensioni di stampa del logo?**
No. Fornisce la base per risolvere gli URL relativi delle risorse. Imposta le dimensioni di inserimento dell'immagine con CSS e controlla separatamente dimensioni e viewBox dell'SVG.

## Fonti

1. [Documentazione API di WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/api_reference.html) — Documenta ingressi HTML, URL base, uscita SVG e comportamento dello zoom PDF.
2. [Primi passi con WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) — Descrive installazione e recupero delle risorse, compresi i limiti di autenticazione.
3. [Documentazione Page di PyMuPDF](https://pymupdf.readthedocs.io/en/latest/page.html) — Documenta i metodi di ispezione di disegni e immagini incorporate usati nell'esempio.

***

Hai soltanto un logo raster? [Prepara un SVG con PerfectVector](https://perfectvector.com/it/vectorize-logo), esamina forme e scritte, poi inseriscilo nell'HTML e verifica aspetto e dimensioni fisiche nel PDF salvato.

## Explore

- [Read the HTML article](https://perfectvector.com/it/blog/weasyprint-svg-image-pdf)
- [Immagini SVG in Graphviz: rendile portabili](https://perfectvector.com/it/blog/graphviz-svg-node-images.md)
- [Icone SVG in MapLibre: controlla pixel e dimensioni](https://perfectvector.com/it/blog/maplibre-svg-symbol-image.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
