Overview
The node provides file system utilities focused on managing and querying files and directories. Specifically, the List Directory operation lists files and folders within a specified directory path with flexible filtering, sorting, and depth traversal options.
This operation is useful when you want to:
- Retrieve an overview of files and subdirectories in a folder.
- Filter results by file type or name patterns.
- Limit the depth of directory traversal.
- Sort results by various attributes like name, modification time, size, etc.
- Control output format (single object vs array).
Practical examples:
- Listing all image files in a media folder for further processing.
- Getting only leaf directories (folders without subfolders) to identify end nodes in a directory tree.
- Sorting files by modification date to process the newest files first.
- Filtering out temporary or backup files using exclude regex patterns.
Properties
| Name | Meaning |
|---|---|
| Directory Path | The root directory path to list files and directories from. Required. |
| Show | Choose what to show in the listing: • Files and Directories • Files Only • Directories Only |
| Only Leaf Folders | If enabled, only directories that do not contain any subdirectories will be returned. Applies only if showing directories or both files and directories. |
| Max Depth | Maximum directory depth to traverse, from 1 (only the specified directory) up to 9 levels deep. |
| Sort By | Attribute to sort the results by: • Name • Modified Time • Type • Size • Depth • Full Path • Parent Directory |
| Sort Direction | Sort order direction: Ascending or Descending. |
| Filter Pattern | Regular expression pattern to include only files/directories matching this pattern. |
| Exclude Pattern | Regular expression pattern to exclude files/directories matching this pattern from the results. |
| Maximum Records | Limits the maximum number of records returned to avoid excessive memory usage. Range: 1 to 5000. |
| Return Single Object | If enabled, returns a single object instead of an array. If multiple results are found, only the first is returned; if none found, returns an empty object. |
Output
The output JSON structure contains one or more objects representing files or directories found in the specified directory path. Each object includes metadata about the file or directory such as:
- Name
- Path
- Type (file or directory)
- Size
- Modification time
- Depth level in the directory tree
- Parent directory
If Return Single Object is enabled, the output JSON contains a single object with a datas property holding either an array of results or a single result.
No binary data is output by this operation.
Dependencies
- Requires access to the local file system where the n8n instance runs.
- No external API keys or services are needed.
- Node execution environment must have permissions to read the specified directories.
Troubleshooting
Error: "Directory path is required"
Ensure the "Directory Path" property is set and points to a valid directory accessible by the n8n runtime.Empty results
Check filter and exclude regex patterns for correctness. An overly restrictive filter or exclude pattern may yield no results.Permission errors
The node needs read permissions on the target directory and its contents. Adjust OS-level permissions accordingly.Performance issues with large directories
Use "Max Depth" and "Maximum Records" properties to limit traversal and result size to prevent high memory usage or long execution times.
Links and References
- Node.js fs module documentation – underlying file system operations reference.
- Regular Expressions Guide – for crafting filter and exclude patterns.