PDFTOSRC(1)

💅 PDFTOSRC 💅

okay so you're looking at pdftosrc(1), a General Commands Manual page, and honestly bestie, it's giving niche-but-iconic. it's a tiny little tool that pulls stuff out of PDF files. that's the vibe. let's get into it ✨

---

🎀 NAME 🎀

pdftosrc — extract source file or stream from PDF file

like literally that's the whole job description and she ate 💅

---

🦋 SYNOPSIS 🦋

pdftosrc PDF-file [stream-object-number]

two args, one optional. simple. clean. main character energy 👑

---

🌸 DESCRIPTION 🌸

so here's the tea. the behavior totally depends on how many args you give her 🫶

if you only pass PDF-file, pdftosrc extracts the embedded source file from the first found stream object with /Type /SourceFile inside the PDF file, and writes it out to a file with the name /SourceName as defined in that PDF stream object (peep the application example way down below for what that looks like irl).

if you pass both PDF-file and stream-object-number, and stream-object-number is positive, pdftosrc extracts and uncompresses the PDF stream of the object given by its stream-object-number from the PDF file, and writes it to a file named PDF-file.stream-object-number — with the ending .pdf or .PDF stripped off from the original PDF-file name. cute, right? 💖

a special case is related to XRef object streams that are part of the PDF standard from PDF-1.5 onward: if stream-object-number equals -1, then pdftosrc decompresses the XRef stream from the PDF file and writes it in human-readable PDF cross-reference table format to a file named PDF-file.xref. and bestie, note this well: these XRef streams cannot be extracted just by giving their object number 😭 that's the whole reason for the -1 special case, iykyk.

in any case, an existing file with the output file name will be overwritten. no warning, no asking, she just goes 💀

✨ Notes ✨

• an embedded source file is written unchanged, i.e., it will not be uncompressed. leaving it exactly as found, periodt.
• only the stream of the object will be written, i.e., not the dictionary of that object. stream only. dictionary stays home 🙈
• knowing which stream-object-number to query requires information about the PDF file that has to be gained elsewhere — e.g., by looking into the PDF file with an editor or dumping it with a utility. she's not gonna tell you, you gotta do your own recon 🔍
• the stream extraction capabilities of pdftosrc (regarding known PDF versions and filter types, for instance) follow the capabilities of the underlying xpdf program version. so whatever xpdf can do, she can do. no more, no less 🧚
• currently the generation number of the stream object is not supported. the default value 0 (zero) is taken. that's just how it is ngl.
• the wording stream-object-number has nothing to do with the object streams introduced by the Adobe PDF Reference, 5th edition, version 1.6. do not confuse them. they are different girlies 💀

---

🌈 EXAMPLES 🌈

an external file, say myfile.zip, can be embedded into a file foo.pdf by using pdfTeX primitives, as illustrated by the following example:

\immediate\pdfobj
    stream attr {/Type /SourceFile /SourceName (myfile.zip)}
    file{myfile.zip} \pdfcatalog{/SourceObject
\the\pdflastobj\space 0 R}

then myfile.zip can be extracted from foo.pdf by calling pdftosrc foo.pdf 🎀

like... that's it. that's the whole ritual 🕯️

---

💜 OPTIONS 💜

• None. — and no, we're not joking. there are literally zero options. she has nothing to configure. she simply is 💅

---

🍓 ENVIRONMENT 🍓

• None. — no environment variables either. nothing to export, nothing to source. go touch grass 🌱

---

🔥 DIAGNOSTICS 🔥

if success, the exit code of pdftosrc is 0, else 1. classic. 💯

all messages go to stderr. at program invocation, pdftosrc issues the current version number of the program xpdf, on which pdftosrc is based, though it is maintained as part of pdfTeX. so yeah, she announces herself every time. main character behavior fr fr 👑

when pdftosrc was successful with the output file writing, one of the following messages will be issued:

Source file extracted to source-file-name

or

Stream object extracted to PDF-file.stream-object-number

or

Cross-reference table extracted to PDF-file.xref

when the object given by the stream-object-number does not contain a stream, pdftosrc issues the following error message:

Not a Stream object

when the PDF-file can't be opened, the error message is:

Error: Couldn't open file 'PDF-file'.

when pdftosrc encounters an invalid PDF file, the error message (several lines) is:

Error: May not be a PDF file (continuing anyway)
(more lines)
Invalid PDF file

there are other error messages from pdftosrc for various kinds of broken PDF files. so if you see something weird, that's just her being honest 😭

---

🦋 BUGS 🦋

not all embedded source files will be extracted — only the first one found. so if you stuffed five files in there, bestie, you're getting one. the first one. that's the deal 🙈

---

⭐ SEE ALSO ⭐

pdfimages(1), pdftex(1), pdftotext(1), xpdf(1) — go read those too, they're all in the family 💖

---

👑 AUTHORS 👑

pdftosrc is part of pdfTeX was written by Hàn The Thành, using xpdf functionality from Derek Noonburg. man page written by Hartmut Henkel 🫶

public discussion list for pdftosrc: https://lists.tug.org/pdftex

---

and that's the page, bestie ✨ this whole thing ships as part of Web2C 2026, dated 16 January 2026 — so like, mark your calendars or whatever 🎀 slay 💅