List Files

List files and directories in a path

Overview

This node lists files and directories from a specified directory path on the filesystem. It supports filtering by file type (files, directories, or both), recursive search into subdirectories, inclusion of hidden files, and various filters such as file extension, name pattern via regex, and file size limits. The results can be sorted and optionally returned as a single array or multiple items.

Common scenarios include:

  • Automating workflows that need to process or analyze files in a directory.
  • Gathering metadata about files for reporting or monitoring.
  • Filtering files based on patterns or size before further processing.
  • Recursively scanning directories to find specific files or folders.

Practical example:

  • List all .js files larger than 1KB recursively in a project folder, excluding hidden files, sorted by modification date descending.
  • Retrieve only directories inside a given path without recursion.
  • Get a limited number of files matching a regex pattern and return them as a single array for batch processing.

Properties

Name Meaning
Directory Path The absolute or relative path of the directory to list files from.
List Mode What type of items to list:
- Files Only
- Directories Only
- Both Files and Directories
Recursive Whether to search subdirectories recursively (true/false).
Include Hidden Files Whether to include hidden files and directories (those starting with a dot .) (true/false).
Filter Options Collection of filters to narrow down results:
- File Extension Filter: Comma-separated list of extensions to include (e.g., .txt,.js,.json).
- Name Pattern (Regex): Regex pattern to match file/directory names.
- Maximum Files: Max number of files to return (0 means no limit).
- Min File Size (bytes): Minimum file size to include (0 means no limit).
- Max File Size (bytes): Maximum file size to include (0 means no limit).
Output Options Collection of output-related options:
- Include File Stats: Whether to include detailed file statistics like size, creation/modification dates, permissions (true/false).
- Return as Single Array: Return all files as one array in a single item instead of multiple items (true/false).
- Sort By: How to sort results (name, size, modified, created, extension).
- Sort Order: Sort order (asc or desc).

Output

The node outputs JSON objects representing each matched file or directory with the following structure:

  • name: File or directory name.
  • path: Absolute path.
  • relativePath: Path relative to the current working directory.
  • type: "file" or "directory".
  • extension: File extension (empty string for directories).
  • size: File size in bytes.
  • sizeHuman: Human-readable file size string.
  • created: Creation date/time.
  • modified: Last modified date/time.
  • accessed: Last accessed date/time.
  • isFile: Boolean indicating if it is a file.
  • isDirectory: Boolean indicating if it is a directory.
  • permissions: Numeric file permission mode.

If "Include File Stats" is disabled, some of these detailed stats may be omitted.

If "Return as Single Array" is enabled, the output will be a single item containing:

  • directoryPath: The resolved directory path.
  • fileCount: Number of files/directories returned.
  • files: An array of the above file/directory objects.
  • searchOptions: Object summarizing the search parameters used.

Binary data is not output by this node.

Dependencies

  • Requires access to the local filesystem where n8n is running.
  • Uses Node.js built-in modules: fs (filesystem operations) and path (path manipulations).
  • No external API keys or services are required.

Troubleshooting

  • Directory path is required: Ensure the "Directory Path" property is set and points to a valid directory.
  • Directory not found: The specified directory does not exist or is inaccessible. Verify the path and permissions.
  • Path is not a directory: The path exists but is not a directory (e.g., a file). Provide a directory path.
  • Permission errors: The node might fail if n8n does not have read permissions for the directory or its contents.
  • Invalid regex pattern: If using a name pattern filter, ensure the regex syntax is correct.
  • Large result sets: Recursive searches with no limits can produce very large outputs; consider setting maximum files or limiting recursion.

To resolve errors, check the error message details provided in the output when "Continue On Fail" is enabled, and adjust input parameters accordingly.

Links and References

Discussion