pdftosrc(1)

💖 pdftosrc(1) — General Commands Manual 💖

okay bestie, gather round, because this little tool is lowkey iconic. it's called pdftosrc, it lives in section 1 of the manual (the general commands girlies), and it does exactly one thing but does it slay: pulling source files and streams out of PDFs. 🦋

---

✨ NAME ✨

pdftosrc — extract source file or stream from PDF file. that's it, that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

pdftosrc PDF-file [stream-object-number]

---

🎀 DESCRIPTION 🎀

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

Case 1: you only give her PDF-file. Then pdftosrc goes hunting for the first found stream object with /Type /SourceFile inside the PDF-file, extracts that embedded source file, and writes it out to a file whose name is whatever /SourceName says inside that PDF stream object. (there's an application example further down, iykyk — go look 👀)

Case 2: you give her both PDF-file and stream-object-number, and stream-object-number is positive. Now she extracts and uncompresses the PDF stream of the object identified 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 the original PDF-file name first. no cap. 🧚

Case 3: the special one, the main character moment. This is about XRef object streams, which 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 out in human-readable PDF cross-reference table format to a file named PDF-file.xref. (these XRef streams literally cannot be extracted just by giving their object number, so this is the only way in. periodt.)

⚠️ in any case, if a file with the output file name already exists, it gets overwritten. gone. reduced to atoms. back up your stuff first, bestie, I'm begging 😭

---

💅 OPTIONS 💅

• none. literally zero options. she has no flags, no switches, no nothing. the lack of options is the aesthetic. ✨

---

🍓 FILES 🍓

just the executable pdftosrc. that's the entire file situation. 🌈

---

🦋 ENVIRONMENT 🦋

none. no environment variables, no secrets, no hidden lore. 🙈

---

👑 DIAGNOSTICS 👑

on success the exit code of pdftosrc is 0. otherwise it's 1. classic.

all messages go to stderr — every single one, not just the scary ones.

when the program starts up, pdftosrc announces the current version number of the program xpdf, which is the thing pdftosrc is based on:

pdftosrc version 3.01

when pdftosrc was successful and the output file got written, you'll get one of these:

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

if the object given by the stream-object-number doesn't actually contain a stream, you get this error:

Not a Stream object

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

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

and if pdftosrc runs into an invalid PDF file, the error message is a whole several-lines situation:

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

there are also more error messages from pdftosrc for various kinds of broken PDF files. so many ways to be broken, so few messages. 💀

---

⭐ NOTES ⭐

• an embedded source file will be written out unchanged — meaning it does not get uncompressed in this process. she's keeping it exactly as she found it, no edits, no notes. 💜
• only the stream of the object gets written out. not the dictionary of that object. stream only. dictionary stays home.
• knowing which stream-object-number to query requires info about the PDF file that you have to get from elsewhere — for example, by opening the PDF file up in an editor and looking inside it yourself. yes, actually looking. 👀
• the stream extraction capabilities of pdftosrc (like which PDF versions and filter types it understands) follow the capabilities of the underlying xpdf program version. she can only do what her xpdf can do.
• currently the generation number of the stream object is not supported. the default value 0 (zero) is what gets taken.
• the wording stream-object-number has nothing to do with the object streams introduced by the Adobe PDF Reference, 5th edition, version 1.6. different thing entirely, do not confuse them, they are not the same girl. 🙅

---

🌈 EXAMPLES 🌈

when you're using pdftex, you can embed a source file into some PDF-file using pdftex primitives, like this:

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

then that zip file can be extracted from the PDF-file by calling:

pdftosrc PDF-file

and boom, out she comes. 🎀

---

💀 BUGS 💀

• not all embedded source files will be extracted — only the first found one. so if you embedded five of them, bestie, you're getting one. 😭
• email bug reports to pdftex@tug.org.

---

🔥 SEE ALSO 🔥

xpdf(1), pdfimages(1), pdftotext(1), pdftex(1),

---

🫶 AUTHORS 🫶

pdftosrc written by Han The Thanh, using xpdf functionality from Derek Noonburg.

man page written by Hartmut Henkel.

---

💖 COPYRIGHT 💖

Copyright (c) 1996-2006 Han The Thanh, <thanh@pdftex.org>

this file is part of pdfTeX.

pdfTeX is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

pdfTeX is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

you should have received a copy of the GNU General Public License along with pdfTeX; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

---

and that's the whole page, bestie 💅 this one came from Web2C 2025, dated 16 June 2015 — a lil vintage, a lil timeless, just like her. go extract something iconic. slay, periodt, bye 🦋✨