Read and write PDF metadata
Add PDFluent to your project
[dependencies]
pdfluent = "1.5.0"Read PDF metadata in Rust
use pdfluent::PdfDocument;
fn main() -> pdfluent::Result<()> {
let doc = PdfDocument::open("report.pdf")?;
let meta = doc.metadata();
println!("title: {:?}", meta.title);
println!("author: {:?}", meta.author);
Ok(())
}Complete program, compiled against the published crate: Code on GitHub →
The same code, typed and run on screen. Watch on YouTube
- Step 1
Open the PDF
Open the document. Metadata is cached on the PdfDocument and read lazily from the Info dictionary on first access.
rustuse pdfluent::prelude::*; let doc = PdfDocument::open("report.pdf")?; - Step 2
Call doc.metadata()
metadata() returns a Metadata struct — a plain snapshot with public fields. There's no Result to unwrap for reads; missing entries surface as None / empty Vec.
rustlet meta = doc.metadata(); println!("title = {:?}", meta.title); println!("author = {:?}", meta.author); - Step 3
Inspect every standard field
Metadata exposes title, author, subject, keywords (Vec<String>), producer, creator, creation_date and modification_date. Dates are PDF D-format strings (e.g. "D:20260421103000+02'00'") — parse them through your preferred date library if you need a DateTime.
rustlet meta = doc.metadata(); if let Some(ref t) = meta.title { println!("T: {}", t); } if let Some(ref a) = meta.author { println!("A: {}", a); } for k in &meta.keywords { println!("K: {}", k); } - Step 4
Bulk-read for a directory of PDFs
Loop over files. Dropping the document at the end of each iteration keeps memory bounded across large batches.
rustuse pdfluent::prelude::*; use std::fs; for entry in fs::read_dir("./inbox")? { let path = entry?.path(); if path.extension().map(|e| e == "pdf").unwrap_or(false) { match PdfDocument::open(&path) { Ok(doc) => { let m = doc.metadata(); println!( "{}: {} — {}", path.display(), m.title.as_deref().unwrap_or("(no title)"), m.author.as_deref().unwrap_or("(no author)"), ); } Err(e) => eprintln!("{}: {}", path.display(), e), } } }
- Metadata.title and Metadata.author are Option<String>; a document may have no title or no author set.
- Metadata.keywords is Vec<String>, parsed from the PDF's /Keywords entry — an empty vector means no keywords.
- creation_date and modification_date are PDF D-format strings; conversion to chrono::DateTime is an application-side concern.
- The 1.0 SDK exposes the Info-dictionary surface on Metadata. Full XMP metadata read (structured RDF) is tracked for a later release.
- Is the Info dictionary always present?
- Most PDFs include it, but a minimal or stripped PDF may not. In that case every Metadata field is None / empty.
- What's the relationship between the Info dictionary and XMP?
- Info is the legacy key/value dictionary PDFluent exposes today. XMP is a richer RDF/XML-based metadata stream used in PDF/A and enterprise workflows. The 1.0 surface reads Info; structured XMP access is tracked for a future release.
- How do I get the page count alongside metadata?
- Call doc.page_count() — it's a separate method on PdfDocument, not part of Metadata.
- Can I read metadata from an encrypted PDF?
- Yes, after decryption. Open the document with PdfDocument::open_with(path, OpenOptions::new().with_password("...")) and call metadata() normally.
Write PDF metadata in Rust
use pdfluent::PdfDocument;
fn main() -> pdfluent::Result<()> {
let mut doc = PdfDocument::open("report.pdf")?;
doc.metadata_mut()
.set_title("Q4 Report")
.set_author("Finance Team")
.commit()?;
doc.save("report-tagged.pdf")?;
Ok(())
}Complete program, compiled against the published crate: Code on GitHub →
The same code, typed and run on screen. Watch on YouTube
- Step 1
Open the PDF for mutation
Open with a mutable binding. MetadataMut borrows &mut on the document for the duration of the builder chain.
rustuse pdfluent::prelude::*; let mut doc = PdfDocument::open("report.pdf")?; - Step 2
Chain setters via metadata_mut()
metadata_mut() returns a MetadataMut builder. Each setter returns &mut Self so you can chain them. Changes are buffered locally — nothing is written until commit().
rustlet mut meta = doc.metadata_mut(); meta.set_title("Q3 Financial Report") .set_author("Finance Team") .set_subject("Quarterly earnings") .set_keywords(&["finance", "q3", "2026"]); - Step 3
Commit to flush changes into the document
commit() writes the buffered changes to the Info dictionary. It returns Result<()>; call it explicitly so you can handle write errors. MetadataMut also flushes on drop, but in that path errors are silenced.
rustdoc.metadata_mut() .set_title("Q3 Financial Report") .set_author("Finance Team") .commit()?; - Step 4
Save the tagged document
save() writes the PDF to disk. The metadata changes are part of that write; no separate flush step required.
rustdoc.save("report_tagged.pdf")?;
- metadata_mut() is infallible — a PDF always has an Info dictionary slot, created lazily by commit() if absent.
- The 1.0 setter surface is set_title, set_author, set_subject, set_keywords. Producer, creator, creation_date and modification_date are read-only in 1.0 (they're written by PDFluent at save time).
- keywords takes a &[&str] and is serialised joined with commas in the PDF's /Keywords entry, which is the common convention.
- Non-ASCII values (titles with accented characters, CJK text) round-trip correctly — PDFluent picks UTF-16BE with BOM when needed.
- Writing metadata does not require any specific capability; it's part of the core SDK surface and available at every tier.
- Do I have to call commit(), or is drop enough?
- commit() lets you handle the Result explicitly. If you rely on drop, any write error is silently dropped. In production code, prefer commit().
- Can I clear a field instead of setting it?
- The 1.0 setters only set values. Clearing a field is tracked as a 1.1 addition. For now, set the field to an empty string or reconstruct the PDF from bytes without the original metadata.
- What encoding is used for non-ASCII titles?
- PDFluent routes metadata strings through lopdf::text_string, which picks PDFDocEncoding for pure ASCII and UTF-16BE with BOM for anything else. Round-trip through read + write is byte-safe.
- Does writing metadata invalidate a digital signature?
- Yes. PDF signatures cover the Info dictionary in most configurations. If you need to change metadata on a signed document, re-sign afterwards.
Write XMP metadata to a PDF in Rust
use pdfluent::{PdfDocument, Metadata};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut doc = PdfDocument::open("whitepaper.pdf")?;
let xmp = Metadata::new()
.title("PDFluent Technical Whitepaper")
.creator("Engineering Team")
.description("Architecture overview of the PDFluent Rust SDK")
.subject(vec!["PDF", "Rust", "SDK"])
.rights("Copyright 2025 PDFluent")
.language("en-US");
doc.set_xmp_metadata(xmp)?;
doc.save("whitepaper_with_xmp.pdf")?;
Ok(())
}- Step 1
Open the PDF
Load the document to which you want to add XMP metadata.
rustuse pdfluent::PdfDocument; let mut doc = PdfDocument::open("report.pdf")?; - Step 2
Build the XMP metadata object
Metadata provides setters for Dublin Core and XMP Basic properties. All fields are optional.
rustuse pdfluent::Metadata; let xmp = Metadata::new() .title("Annual Report 2025") .creator("Finance Department") .description("Consolidated financial statements for fiscal year 2025") .subject(vec!["Finance", "Annual Report", "2025"]) .publisher("Acme Corp") .rights("All rights reserved") .language("en-GB") .creation_date("2025-03-01T09:00:00Z") .modify_date("2025-04-14T15:30:00Z"); - Step 3
Add a custom XMP namespace and property
Register a custom namespace to store application-specific metadata alongside the standard Dublin Core fields.
rustlet xmp = xmp .custom_namespace("http://ns.acme.com/pdf/1.0/", "acme") .custom_property("acme:documentId", "DOC-2025-0042") .custom_property("acme:department", "Legal") .custom_property("acme:confidentiality", "Internal"); - Step 4
Write the metadata and save
set_xmp_metadata() serialises the XMP packet and embeds it in the PDF. Existing XMP metadata is replaced.
rustdoc.set_xmp_metadata(xmp)?; doc.save("report_with_xmp.pdf")?; println!("XMP metadata written.");
- XMP metadata in PDFs is stored as an XML packet in the /Metadata stream of the document catalog.
- Setting XMP metadata does not change the DocInfo dictionary (/Author, /Title, etc.). Use doc.set_info() to set both.
- XMP supports multi-language values via xml:lang attributes. Use .title_lang("fr-FR", "Rapport Annuel") for localised titles.
- After calling set_xmp_metadata(), any existing digital signature becomes invalid. Set metadata before signing.
- What is the difference between XMP metadata and the PDF Info dictionary?
- The Info dictionary (/Author, /Title, /Subject, etc.) is the older PDF metadata format. XMP is the modern extensible format. Some tools read one, some read both. PDFluent lets you set both independently.
- How do I read back the XMP metadata I wrote?
- Call doc.xmp_metadata() which returns an Option<Metadata>. Access fields with the same getter methods.
- Can I embed a raw XMP XML string instead of using the builder?
- Yes. Use doc.set_raw_xmp(xml_string) to embed an already-serialised XMP packet. PDFluent validates the XML is well-formed before embedding it.
- Is XMP metadata preserved when I merge PDFs?
- The merged document uses the XMP metadata from the first input file. After merging, call set_xmp_metadata() on the result to write correct metadata for the combined document.
Read the PDF spec version from a document in Rust
use pdfluent::PdfDocument;
fn main() -> pdfluent::Result<()> {
let doc = PdfDocument::open("file.pdf")?;
let v = doc.version();
println!("PDF {}.{}", v.major, v.minor);
Ok(())
}- Step 1
Open the document and call pdf_version()
pdf_version() reads the %PDF-x.y header from the first 8 bytes of the file. It does not require full document parsing.
rustuse pdfluent::PdfDocument; let doc = PdfDocument::open("document.pdf")?; let version = doc.version(); println!("{}.{}", version.major, version.minor); - Step 2
Compare versions with the PdfVersion enum
Use predefined constants to write readable version checks. PdfVersion implements PartialOrd.
rustlet v = doc.version(); match (v.major, v.minor) { (1, 0) => println!("Very old document"), (1, 4) => println!("PDF 1.4 - supports transparency"), (1, 5) => println!("PDF 1.5 - supports object streams"), (1, 6) => println!("PDF 1.6 - supports AES-128"), (1, 7) => println!("PDF 1.7 - supports AES-256"), (2, 0) => println!("PDF 2.0 - latest standard"), _ => println!("Other version: {}.{}", v.major, v.minor), } - Step 3
Read version without fully opening the document
Use PdfDocument::peek_version() to read only the header bytes. This is faster when you need to filter files before loading them.
rustuse pdfluent::PdfDocument; let doc = PdfDocument::open("document.pdf")?; let version = doc.version(); println!("PDF {}.{}", version.major, version.minor); // Only proceed for documents that are at least PDF 1.6 if (version.major, version.minor) >= (1, 6) { // ... }
- The version in the %PDF header is the declared version. Some tools update the DocumentCatalog Version entry without changing the header. PDFluent returns the higher of the two values.
- PDF 2.0 (ISO 32000-2) is the current standard. PDF 1.7 (ISO 32000-1) is still the most common version in real-world documents.
- Versions below 1.4 do not support transparency groups. Versions below 1.5 do not support cross-reference streams.
- What is the difference between the header version and the catalog version?
- The %PDF-x.y header declares the minimum version needed to read the file. The Version entry in the DocumentCatalog can override it for incrementally updated documents. PDFluent reports the effective version, which is the maximum of both.
- Can I upgrade the PDF version with PDFluent?
- Yes. Call doc.set_pdf_version(PdfVersion::V1_7) and save the document. This only updates the declared version. It does not enable or migrate features automatically.
- Does peek_version() read the entire file?
- No. peek_version() reads only the first 8 bytes of the file, which is where the %PDF-x.y header lives. It is suitable for filtering large batches of files without memory overhead.
- What version does PDFluent produce when creating a new document?
- PdfDocument::create() makes an empty document with a single blank US Letter page at PDF 1.7. There is no version override, and no way to add content to it -- PDFluent works on documents that already exist.
Detect if a PDF is linearized (web-optimized) in Rust
use std::fs::File;
use std::io::Read;
fn main() -> pdfluent::Result<()> {
// PDFluent 1.0 has no linearization reader. What can be read without one is
// the claim: the /Linearized dictionary is by definition the first object of
// a linearized file, so it is in the first kilobyte if it is anywhere.
let mut head = [0u8; 1024];
let read = File::open("file.pdf")?.read(&mut head)?;
let claims_linearized = String::from_utf8_lossy(&head[..read]).contains("/Linearized");
// A claim, not a verdict: nothing here proves the token belongs to that
// dictionary rather than to a string or a comment, and nothing checks that
// the offsets it carries still describe the file.
println!("claims fast web view: {claims_linearized}");
Ok(())
}- Step 1
Read the first kilobyte
A linearized file puts its linearization dictionary before anything else, so no PDF parser is needed to look for it -- and nothing else in the file has to be read.
rustuse std::fs::File; use std::io::Read; let mut head = [0u8; 1024]; let read = File::open("file.pdf")?.read(&mut head)?; - Step 2
Look for the key, and treat it as a claim
The dictionary is recognisable by its /Linearized entry. A hit says the file presents itself as linearized; it does not prove the token belongs to the first indirect object, and it says nothing about whether the offsets in that dictionary are still true. For a verdict you need a parser that walks the dictionary -- 1.0 does not have one.
rustlet claims = String::from_utf8_lossy(&head[..read]).contains("/Linearized"); if claims { println!("The file claims fast web view. The claim is not verified here."); } else { println!("No linearization dictionary in the first kilobyte."); } - Step 3
Open it with PDFluent for everything else
The check above is about the byte order the file claims for itself. Everything about its content comes from opening it as usual.
rustuse pdfluent::PdfDocument; let doc = PdfDocument::open("file.pdf")?; println!("{} pages, PDF {}", doc.page_count(), doc.version());
- There is no doc.is_linearized() in PDFluent 1.0, and no linearization_info() or validate_linearization() either. This page shows the check that does work, rather than a call that would have to be invented for it.
- It is a claim and not a verdict. /Linearized could sit inside a string, a comment or an unrelated object, and a real reader would have to parse the first indirect object and check the offsets and the hint stream against the file.
- The key only says the file was linearized once. Any edit after that -- an added page, an incremental signature -- leaves the key in place while the offsets it carries stop being true.
- Linearization only pays off over HTTP with byte-range requests enabled. For a download or a local file it changes nothing.
- PDFluent 1.0 does not produce linearized files either; see the section on linearizing a PDF for what the call does today.
- Why is there no is_linearized() on PdfDocument?
- Because linearization is not in 1.0 at all: nothing in the library produces it, and a reader that only answers about other people's files was not worth a call that would then be the only one of its kind. The four lines above are the whole check.
- Is this the same as compression?
- No. Linearization changes the order of the objects in the file so a viewer can show page one before the rest arrives. Compression changes their size. They are independent.
- Does it change what the document looks like?
- No. It is a reordering of the file's internals; pages, fonts and images are untouched.
Linearize a PDF for faster web loading in Rust
use pdfluent::{Error, PdfDocument};
fn main() -> pdfluent::Result<()> {
let mut doc = PdfDocument::open("brochure.pdf")?;
match doc.linearize() {
// Only this branch produces a fast-web-view file.
Ok(()) => {
doc.save("brochure_linear.pdf")?;
println!("brochure_linear.pdf is linearized");
}
// 1.0 does not build hint streams, and the call refuses out loud rather
// than writing an ordinary file and calling it fast web view. So say so,
// and write the file under a name that does not claim otherwise.
Err(Error::Unsupported(what)) => {
doc.save("brochure.pdf.out")?;
println!("not in this release: {what}");
println!("brochure.pdf.out is written and NOT linearized; run qpdf --linearize over it");
}
Err(e) => return Err(e),
}
Ok(())
}- Step 1
Open the PDF
Linearizing rewrites the order of the objects in the file, so the document is opened for modification.
rustuse pdfluent::PdfDocument; let mut doc = PdfDocument::open("catalogue.pdf")?; - Step 2
Ask for it, and let the two outcomes write different files
linearize() is on PdfDocument and returns Error::Unsupported in 1.0: hint-stream construction and the object reordering behind it are a 1.x MINOR. Saving still works -- but a file saved after the refusal is an ordinary PDF, so do not give it a name that claims fast web view, and do not let a pipeline treat the two outcomes as one. SaveOptions::with_linearize(true) is refused for the same reason rather than quietly ignored.
rustuse pdfluent::Error; match doc.linearize() { Ok(()) => { doc.save("catalogue_linear.pdf")?; println!("linearized"); } Err(Error::Unsupported(what)) => { doc.save("catalogue_plain.pdf")?; println!("skipped: {what}; catalogue_plain.pdf is not linearized"); } Err(e) => return Err(e), } - Step 3
Linearize with an external tool for now
qpdf does it as a post-step over the file PDFluent wrote, and it is the tool the API documentation itself points at until the engine grows its own. Serve the result with Accept-Ranges: bytes.
rustqpdf --linearize catalogue_plain.pdf catalogue_linear.pdf
- PDFluent 1.0 does not linearize. doc.linearize() exists and returns Error::Unsupported, and SaveOptions::with_linearize(true) is refused rather than ignored. Both are deliberate: the alternative is a call that returns Ok on a file it did not touch.
- There is no LinearizeOptions type. Nothing configures a linearizer that is not there.
- Linearization only helps when the file is served over HTTP with byte-range requests enabled (Accept-Ranges: bytes).
- Any modification after linearizing -- extra pages, an incremental signature -- undoes it. It belongs at the end of a pipeline, not in the middle.
- When does PDFluent linearize?
- It is a 1.x MINOR: it needs hint-stream construction and a different object order in the writer, which is a change to how files are written rather than an option on top of it.
- Why does the call exist if it always fails?
- So that code written against it keeps working when it lands, and so the gap is visible where it matters. The alternative -- no call, or a call that silently does nothing -- either hides the gap or produces files that claim something untrue.
- Does signing break linearization?
- Incremental signing appends to the file without reordering it, so a strictly linearized file stops being one. Linearize after signing if fast web view matters.