Attachments
A PDF can carry files inside it: the XML of an invoice for the software that books it, the spreadsheet a report was made from, or the terms that go with an offer. A reader lists them in its attachments panel, and saves or opens them from there. Lpdf embeds the files a document lists in its attachments, as they are: it does not draw them.
<lpdf version="1"> <document> <attachments> <file name="invoice.xml" src="data/invoice-2026-0412.xml" mime="text/xml" relationship="data" description="The invoice as data, for software to read"/> <file name="terms.pdf" src="terms.pdf" mime="application/pdf" relationship="supplement"/> </attachments> <section> <layout margin="48pt"> <text font-size="24pt">Invoice 2026-0412</text> <text>The invoice data and the terms of sale are attached to this PDF.</text> </layout> </section> </document></lpdf>L.document({ attachments: [{ name: 'invoice.xml', src: 'data/invoice-2026-0412.xml', mime: 'text/xml', relationship: 'data', description: 'The invoice as data, for software to read' }, { name: 'terms.pdf', src: 'terms.pdf', mime: 'application/pdf', relationship: 'supplement' }] }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.text({ fontSize: '24pt' }, ['Invoice 2026-0412']), L.text(NoAttr, ['The invoice data and the terms of sale are attached to this PDF.']), ]), ]),])L.document(DocumentAttr(attachments=[FileAttr(name='invoice.xml', src='data/invoice-2026-0412.xml', mime='text/xml', relationship='data', description='The invoice as data, for software to read'), FileAttr(name='terms.pdf', src='terms.pdf', mime='application/pdf', relationship='supplement')]), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.text(TextAttr(font_size='24pt'), ['Invoice 2026-0412']), L.text(NoAttr, ['The invoice data and the terms of sale are attached to this PDF.']) ]) ])])L.document(new DocumentAttr().attachments(List.of(new FileAttr().name("invoice.xml").src("data/invoice-2026-0412.xml").mime("text/xml").relationship("data").description("The invoice as data, for software to read"), new FileAttr().name("terms.pdf").src("terms.pdf").mime("application/pdf").relationship("supplement"))), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.text(new TextAttr().fontSize("24pt"), List.of("Invoice 2026-0412")), L.text(NoAttr, List.of("The invoice data and the terms of sale are attached to this PDF.")) )) ))))L.Document(new() { Attachments = [new FileAttr { Name = "invoice.xml", Src = "data/invoice-2026-0412.xml", Mime = "text/xml", Relationship = "data", Description = "The invoice as data, for software to read" }, new FileAttr { Name = "terms.pdf", Src = "terms.pdf", Mime = "application/pdf", Relationship = "supplement" }] }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Text(new() { FontSize = "24pt" }, ["Invoice 2026-0412"]), L.Text(NoAttr, ["The invoice data and the terms of sale are attached to this PDF."]), ]), ]),])L::document(new DocumentAttr(attachments: [new FileAttr(name: 'invoice.xml', src: 'data/invoice-2026-0412.xml', mime: 'text/xml', relationship: 'data', description: 'The invoice as data, for software to read'), new FileAttr(name: 'terms.pdf', src: 'terms.pdf', mime: 'application/pdf', relationship: 'supplement')]), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::text(new TextAttr(fontSize: '24pt'), ['Invoice 2026-0412']), L::text(NoAttr, ['The invoice data and the terms of sale are attached to this PDF.']), ]), ]),])The attachments element
Section titled “The attachments element”attachments sits in document, after meta and output and before the sections. It holds one file for each file the PDF carries.
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | required | The name a reader shows the file under and saves it as, such as invoice.xml. Each file of a document has a name of its own |
src |
path | — | Where the SDK reads the file from, when it was not loaded on the engine |
ref |
string | the name | The key the file was loaded on the engine under, when that is not its name |
mime |
string | application/octet-stream |
The type of the file, such as text/xml, application/pdf or text/csv: a type and a subtype. Without it a reader knows only that it is a file |
relationship |
source data alternative supplement unspecified |
unspecified |
How the file relates to the document: the file it was made from, the data its pages show, the same content in another form, or more than the pages show. The XML of a Factur-X invoice gets the one its profile asks for |
description |
string | — | A line about the file, which a reader shows beside its name |
The files belong to the whole document. A file pinned to a spot on a page, or tied to one image or table, is not written.
The bytes
Section titled “The bytes”The bytes of a file come as an image’s do. The SDK reads src, relative to the working directory of your app, or you load the bytes on the engine yourself, under the file’s name or its ref. A file loaded on the engine is used for every render of that engine, and its src, if it has one, is not read.
import { L } from '@lpdfio/lpdf'import { readFileSync, writeFileSync } from 'node:fs'
const pdf = await L.engine() .loadFile('invoice.xml', readFileSync('data/invoice-2026-0412.xml')) .render(xml)
writeFileSync('invoice.pdf', pdf)from pathlib import Pathfrom lpdf import L
pdf = (L.engine() .load_file('invoice.xml', Path('data/invoice-2026-0412.xml').read_bytes()) .render(xml))
Path('invoice.pdf').write_bytes(pdf)import io.lpdf.EngineOptions;import io.lpdf.L;import java.nio.file.Files;import java.nio.file.Path;
byte[] pdf = L.engine(new EngineOptions().srcFallback(src -> Files.readAllBytes(Path.of(src)))) .loadFile("invoice.xml", Files.readAllBytes(Path.of("data/invoice-2026-0412.xml"))) .render(xml);
Files.write(Path.of("invoice.pdf"), pdf);Java reads a src only through the engine’s srcFallback, as it does an image’s: here it reads terms.pdf. Without one, a file with a src that was not loaded is an error that says so.
using Lpdf;using Lpdf.Engine;
using var engine = L.Engine(new EngineOptions { SrcFallback = File.ReadAllBytes });engine.LoadFile("invoice.xml", await File.ReadAllBytesAsync("data/invoice-2026-0412.xml"));var pdf = engine.Render(xml);
await File.WriteAllBytesAsync("invoice.pdf", pdf);C# reads a src only through the engine’s SrcFallback, as it does an image’s: here it reads terms.pdf. Without one, a file with a src that was not loaded is an error that says so.
<?phprequire_once 'vendor/autoload.php';
use Lpdf\L;
$pdf = L::engine() ->loadFile('invoice.xml', file_get_contents('data/invoice-2026-0412.xml')) ->render($xml);
file_put_contents('invoice.pdf', $pdf);A document built in code lists its files in attachments, a list of FileAttr with the attributes of file: attachments: [{ name: 'invoice.xml', mime: 'text/xml', relationship: FileRelationship.Data }] in JavaScript, attachments(List.of(…)) on DocumentAttr in Java, Attachments in C#. FileRelationship holds the five relationships.
Size and memory
Section titled “Size and memory”A file has no size limit of its own: its bytes count toward the render’s memory cap, 1024 MB unless the engine sets another. In the Python, Java, C# and PHP SDKs the bytes travel to the engine as base64 in a JSON request, so a large file costs several times its size in memory while it renders, and each copy counts toward the cap: the request, the bytes the engine decodes and the PDF that holds them. The SDK holds the request and the PDF sent back besides. JavaScript hands the bytes to the engine directly, before the render, so only the PDF that holds them counts.
Encryption, PDF/A and PDF/X
Section titled “Encryption, PDF/A and PDF/X”In an encrypted document the files are encrypted with the rest, under the same passwords.
A PDF/A-2 file can carry only files that are PDF/A themselves, which the engine can’t check, so attachments with pdfa="2a", "2b" or "2u" is an error. PDF/A-3, pdfa="3a", "3b" or "3u", carries files of any kind. In a PDF/A-3 document, a file named factur-x.xml makes the PDF a Factur-X e-invoice.
A PDF/X file holds only what the press prints, so attachments with pdfx is an error. What combines with what has the other pairs.
Errors
Section titled “Errors”Each of these stops the render with an error that says what to change:
- a file with no bytes: no
src, and nothing loaded under its name orref. The error names the key to load it under - a
srcthe SDK can’t read. The error names the file and the path - two files with the same name
- a
relationshipthat isn’t one of the five, or amimethat isn’t a type and a subtype - a file without a name
- a file over 2 GB
attachmentsin a document whoseoutputasks forpdfa="2a",pdfa="2b",pdfa="2u"orpdfx- a file named
factur-x.xmlorxrechnung.xmlin a document that is not PDF/A-3: see Factur-X / ZUGFeRD