pdfdetach: List and extract PDF attachments

pdfdetach is a small, focused tool for working with attachments inside PDF files. It can simply list what’s embedded or extract selected items.

Quick starts (examples first)

  • List all attachments in a PDF (default encoding):
pdfdetach list {{path/to/input.pdf}}
  • List with explicit UTF-8 encoding (avoid encoding surprises):
pdfdetach list -enc {{UTF-8}} {{path/to/input.pdf}}
  • Save a specific attachment by its number:
pdfdetach -save {{number}} {{path/to/input.pdf}}
  • Save by the attachment’s name:
pdfdetach -savefile {{name}} {{path/to/input.pdf}}
  • Save the attachment to a custom output directory/filename:
pdfdetach -save {{number}} -o {{path/to/output}} {{path/to/input.pdf}}
  • If the PDF is password-protected, you can supply the owner or user password:
pdfdetach -save {{number}} {{-opw|-upw}} {{password}} {{path/to/input.pdf}}

What each command does

  • list: prints the attachments and their metadata. Can help you decide which one to extract.
  • -save: extracts an attachment by its index number. The output location defaults to the current directory unless you specify -o.
  • -savefile: extracts by the attachment name, which is handy if you know what you’re after.
  • -o: specifies an output directory for the extracted file.
  • -enc: controls text encoding when listing, avoid garbled names in non-UTF-8 PDFs.
  • -opw / -upw: supply an owner or user password if the document is protected.

Common pitfalls

  • Forgetting -o: Without -o, you’ll still get a file in the current directory. Always specify an output path if you’re automating the process.
  • Special characters in filenames: Attachments may have spaces or unusual characters. Use -savefile with the proper name, or quote paths in your shell.
  • Encoding surprises: PDF attachment names may not be UTF-8 by default. If you see garbled names, try -enc UTF-8 or inspect metadata first with pdfdetach list -enc.
  • Passwords: If you’re unsure whether a file is password-protected, try listing first; if listing fails, attempt extraction with -opw or -upw only after confirming the password.

When to use pdfdetach vs alternatives

  • pdfdetach is ideal when you know you need only attachments, not the full PDF text or images.
  • If you’re exploring PDFs for images or text, tools like pdfimages or pdfinfo can complement pdfdetach.

Tiny troubleshooting checklist

  • No attachments listed? Verify you opened the correct file and that it actually has embedded files.
  • Extraction fails with a password error? Make sure you’re using the right password type (-opw for owner, -upw for user).
  • Output files missing after run? Check your current directory or the -o path; ensure you have write permissions there.

Summary

pdfdetach provides a concise way to discover and retrieve embedded PDFs attachments with minimal fuss. Start by listing to identify targets, then extract with the appropriate -save or -savefile option, handling encoding and passwords as needed.

See Also