List Files

List files and directories in a path
Join our community

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 through subdirectories, inclusion of hidden files, and various filters such as file extension, name pattern (regex), file size limits, and maximum number of files to return. The results can be sorted by different criteria and optionally include detailed file statistics.

Common scenarios where this node is useful include:

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

Practical example:

  • List all .js files recursively in a project folder, excluding hidden files, and sort them by modification date descending.
  • Retrieve all directories only within a given path without recursion.
  • Get a limited number of files larger than 1MB with detailed stats for backup or archival workflows.

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", or "Both Files and Directories".
Recursive Whether to search subdirectories recursively (true or false).
Include Hidden Files Whether to include hidden files and directories (those starting with a dot .).
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 = no limit).
- Min File Size (bytes): Minimum file size (0 = no limit).
- Max File Size (bytes): Maximum file size (0 = no limit).
Output Options Collection of output preferences:
- Include File Stats: Whether to include detailed file statistics like size, creation/modification dates, permissions.
- Return as Single Array: Return all files as one array in a single item.
- Sort By: Criteria to sort results by ("Name", "Size", "Modified Date", "Created Date", "Extension").
- Sort Order: Sort order, ascending or descending.

Output

The node outputs JSON data representing the files and/or directories found according to the input parameters.

  • If Return as Single Array is enabled, the output contains one item with a JSON object including:

    • directoryPath: The resolved absolute directory path.
    • fileCount: Number of files/directories returned.
    • files: An array of file/directory objects.
    • searchOptions: The options used for the search (filters, recursion, etc.).

  • Otherwise, each file or directory is output as a separate item with JSON containing:

    • name: The file or directory name.
    • path: Absolute path to the file or directory.
    • relativePath: Path relative to the current working directory.
    • type: Either "file" or "directory".
    • If file stats are included:
      • extension: File extension (for files).
      • size: File size in bytes.
      • sizeHuman: Human-readable file size.
      • created, modified, accessed: Timestamps for creation, last modification, and last access.
      • isFile, isDirectory: Boolean flags.
      • permissions: File mode/permissions.

No binary data is output by this node.

Dependencies

  • Requires access to the local filesystem where n8n is running.
  • Uses Node.js built-in modules: fs (filesystem) and path.
  • No external API keys or services are required.
  • Ensure the n8n instance has appropriate permissions to read the target directories.

Troubleshooting

  • Directory not found error: Occurs if the specified directory path does not exist. Verify the path is correct and accessible.
  • Path is not a directory error: Happens if the path points to a file instead of a directory. Provide a valid directory path.
  • Permission errors: If n8n lacks permission to read the directory or its contents, the node will fail. Adjust filesystem permissions accordingly.
  • Invalid regex pattern: If the name pattern filter contains an invalid regular expression, it may cause errors. Validate regex syntax before use.
  • Large directories with recursion: Recursive listing on large directory trees may impact performance or memory usage. Use filters and max files limits to mitigate.

If the node is set to continue on failure, errors for individual items will be output as JSON with an error field describing the issue.

Links and References

Discussion