PyMuPDF4LLM GUI: convertire PDF in markdown senza codice

Chi lavora con i modelli di linguaggio sa che il formato in cui si fornisce il testo conta. Un PDF di 40 pagine incollato così com’è in una chat consuma token in modo inefficiente, perché il modello deve processare anche la struttura di layout, le intestazioni ripetute, i metadati invisibili. Lo stesso contenuto convertito in markdown pesa molto meno in termini di token e risulta più facile da elaborare per il modello.

Esistono convertitori online, ma se si cerca qualcosa per lavorare in locale convertire un PDF in markdown non è mai stato un’operazione banale. Gli strumenti disponibili sono da usare da terminale o da integrare in script. Per chi non programma, o per chi semplicemente vuole convertire un documento al volo senza aprire un terminale, le opzioni sono poche.

PyMuPDF4LLM GUI nasce per risolvere questo problema specifico, offrendo un’interfaccia web locale che permette di convertire PDF in markdown con un drag-and-drop e qualche clic.

Perché PyMuPDF4LLM e non PyMuPDF

La distinzione merita una spiegazione, perché i due nomi si assomigliano ma fanno cose diverse.

PyMuPDF è una libreria Python molto potente per lavorare con i PDF. Permette di estrarre testo, immagini, metadati e di manipolare i documenti in vari modi. È veloce, stabile e ben documentata. Il punto è che PyMuPDF estrae testo grezzo, senza preservare la struttura logica del documento. Il risultato richiede un lavoro di post-elaborazione significativo per ricostruire heading, tabelle, elenchi e la gerarchia del contenuto.

PyMuPDF4LLM è un’estensione specializzata di PyMuPDF, progettata specificamente per produrre output ottimizzato per i modelli di linguaggio. Il risultato è markdown strutturato che preserva heading, tabelle, elenchi puntati e la gerarchia logica del documento originale. Supporta l’analisi del layout (incluse le pagine a colonne multiple), l’estrazione delle immagini, il riconoscimento ottico dei caratteri per i PDF scansionati e l’integrazione diretta con framework come LlamaIndex e LangChain.

In pratica PyMuPDF4LLM fa esattamente quello che serve quando si vuole dare un PDF a un LLM, produce un markdown pulito e ben strutturato, pronto da usare.

Il problema dell’accessibilità

PyMuPDF4LLM è un’ottima libreria, ma si usa da terminale o dentro a script Python. L’utilizzo minimo richiede di aprire un ambiente Python, importare il modulo, specificare il percorso del file e lanciare la conversione. Per chi lavora quotidianamente con Python non è un ostacolo. Per chi usa i modelli di linguaggio come strumento di lavoro senza essere sviluppatore, è una barriera.

L’idea della GUI è nata lavorando con ADA, la mia app che costruisce team virtuali di esperti, osservando quanto si riducono i pesi dei file quando si converte un PDF in markdown. La differenza è notevole e ho pensato che avere un’interfaccia grafica per questa conversione potesse essere utile a me e ad altri, soprattutto a chi non ha familiarità con il terminale.

Come funziona PyMuPDF4LLM GUI

L’interfaccia è un’applicazione web locale basata su Flask. Si avvia con un doppio clic su un file batch (Windows) o uno script shell (Mac/Linux) e si apre nel browser. Nessun dato lascia il computer, tutto il processamento avviene in locale.

Il flusso di lavoro è semplice. Si trascina un PDF nell’area di upload (o lo si seleziona con il file picker), si regolano le opzioni di conversione se necessario e si preme un pulsante. In pochi secondi il markdown compare nell’area di anteprima, con evidenziazione della sintassi per heading, tabelle, link e immagini. Da lì è possibile copiare il testo negli appunti o scaricarlo come file “.md“

Le funzionalità

La GUI espone le opzioni più utili di PyMuPDF4LLM, organizzate in modo da rendere immediati i casi d’uso comuni e accessibili le configurazioni più avanzate.

Opzioni essenziali (sempre visibili):

• Selezione pagine: si possono specificare le pagine da convertire con una sintassi come 1-5, 8, 12, utile per lavorare solo sulle sezioni rilevanti di un documento lungo;
• Gestione immagini: tre modalità tra cui scegliere, ignorare le immagini, incorporarle in base64 nel markdown o salvarle come file separati;
• Strategia tabelle: quattro modalità di riconoscimento (strict per tabelle con bordi netti, lines, text per allineamento, oppure disattivato) per adattarsi ai diversi tipi di layout;
• OCR: riconoscimento ottico dei caratteri per i PDF scansionati, attivabile con un clic.

Opzioni avanzate (sezione espandibile):

• Lingua OCR: codice lingua Tesseract (ad esempio “ita”, “deu”), utile per documenti non in inglese (il default);
• OCR forzato: applica il riconoscimento anche su PDF con testo nativo, per i casi in cui il testo estratto risulta corrotto o incompleto;
• Margini: permette di escludere header e footer specificando i margini in punti (alto, destra, basso, sinistra);
• DPI: risoluzione delle immagini estratte, regolabile da 72 a 600;
• Suddivisione per pagina: produce un blocco markdown separato per ogni pagina, con separatore visivo.

Gestione delle immagini e download: quando si sceglie di salvare le immagini come file separati, la GUI crea automaticamente un archivio ZIP con il file markdown e una cartella contenente tutte le immagini estratte. I percorsi nel markdown usano path relativi e sono pronti per essere usati senza modifiche. Le immagini estratte possono essere fornite ai modelli multimodali insieme al testo.

Anteprima e copia: il markdown convertito compare nell’area di anteprima con evidenziazione della sintassi per heading, tabelle, link e immagini. Da lì è possibile copiare il testo negli appunti o scaricarlo come file “.md”

Interfaccia bilingue: l’interfaccia è disponibile in inglese e italiano. Ho aggiunto questa funzione perché buona parte del mio pubblico lavora in italiano, ma la lingua predefinita è l’inglese per rendere il progetto accessibile a livello internazionale. La preferenza viene salvata automaticamente per le sessioni successive.

Il risparmio di token, in concreto

Il vantaggio più immediato della conversione PDF-to-markdown riguarda i token. Un PDF caricato direttamente in un modello di linguaggio viene processato con tutta la sua struttura visiva, che include informazioni di layout, font, posizionamento e metadati che al modello non servono per comprendere il contenuto.

Lo stesso documento convertito in markdown contiene solo il testo e la sua struttura logica (heading, elenchi, tabelle, link). Il risultato è un consumo di token sensibilmente inferiore, che si traduce in costi più bassi per chi usa le API e in più spazio nella finestra di contesto per tutti.

Con documenti lunghi la differenza diventa rilevante. Un report di 50 pagine che in formato PDF satura la finestra di contesto di un modello potrebbe, in formato markdown, lasciare spazio sufficiente per le istruzioni di analisi e per la conversazione che segue.

Installazione e requisiti

Il progetto richiede Python 3.10 o successivo, Flask e PyMuPDF4LLM. L’installazione dell’app si completa in pochi passaggi. Si clona il repository da GitHub, si installano le dipendenze con pip install -r requirements.txt e si avvia l’applicazione con lo script fornito, le istruzioni complete sono nella pagina Github.
Il browser si apre automaticamente sulla pagina di conversione.

Il repository è disponibile su GitHub con licenza MIT.

Un progetto di vibe coding

PyMuPDF4LLM GUI è nato interamente in vibe coding con il modello Opus 4.6 di Claude. Dall’idea iniziale al design dell’interfaccia, dal backend Flask alla gestione delle immagini, ogni componente è stato sviluppato in conversazione con il modello. Il tutto ha richiesto circa mezza giornata, con il promo prototipo funzionante già disponibile al primo tentativo (questo grazie ad un contesto ben descritto). Il resto del tempo è stato impiegato per lavorare sull’estetica, generare la documentaazione per Github e relativa pubblicazione, la scrittura di questo articolo.