Sparround

Files and binary data

Binary data is any file-type data: images, PDFs, CSVs, archives. It lives inside the item under the binary key, separate from json.

Three main nodes handle files:

  • Extract From File — pulls data out of a binary format into JSON (CSV, PDF, XLSX, text)
  • Convert to File — turns JSON data into a file (CSV, XLSX, text, base64)
  • Read/Write Files from Disk — reads and writes files on the machine n8n runs on

Alongside them: dedicated HTML and XML nodes, Compression for archives, Edit Image for images, and FTP for remote servers. To react to a local file changing, use the Local File Trigger.

ScenarioNode chain
Write a CSV attachment from an email into a sheetGmail Trigger → Extract From File (CSV) → Google Sheets
Send a report as an Excel filePostgres → Convert to File (XLSX) → Gmail (attachment)
Extract data from a PDF invoiceTrigger → Extract From File (PDF) → AI (fill the fields) → accounting system
Scrape data from a web pageHTTP Request → HTML (Extract) → Edit Fields
Unpack an archive and process its contentsTrigger → Compression (Decompress) → Extract From File

Reaching binary data from an expression. $('Node name').item.binary returns an object: an item can hold several binary properties, each under its own name. Most nodes emit theirs as data, but it depends on the node — so check the node's output for the actual name.

For example, to get the file name produced by an HTTP Request node: {{ $('HTTP Request').item.binary.data.fileName }}

Memory is the main concern. Binary data travels inside the item, so large files hit memory directly. Processing twenty 50 MB files in one execution easily causes memory problems. On self-hosted, how binary data is stored — in memory or on the filesystem — is tunable with environment variables, and that is an important part of scaling.

Reading and writing files has security implications — it means access to the disk of the machine n8n runs on. In a self-hosted setup where that capability is not needed, the relevant nodes can be disabled entirely with an environment variable.

📚 Sources and documentation