Files.walk and DirectoryStream: Traversing Directories

Java NIO.2 provides several complementary APIs for walking directory trees: Files.walk() returns a lazy Stream that integrates naturally with the stream pipeline API; Files.walkFileTree() offers a visitor pattern with fine-grained control over recursion; DirectoryStream gives efficient, single-level directory listing with optional glob or attribute filtering; and Files.list() is a non-recursive Stream-based alternative. This article covers all four approaches with real examples.

Share

Contents

Files.walk() basics

Files.walk() returns a lazy Stream<Path> that traverses a directory tree depth-first, including the starting path itself as the first element. The stream must always be closed, it holds an open file-system handle, so wrap it in try-with-resources every time. An overload accepts a maxDepth argument to limit how deep the traversal goes: depth 1 yields only the immediate children, depth 2 adds grandchildren, and so on.

Java
import java.nio.file.*;
import java.io.IOException;

// Files.walk(start) — depth-first, includes the start path itself
// Returns a lazy Stream<Path>; MUST be closed (try-with-resources)
Path root = Path.of("/home/user/projects");

try (Stream<Path> stream = Files.walk(root)) {
    stream.forEach(System.out::println);
}
// /home/user/projects
// /home/user/projects/myapp
// /home/user/projects/myapp/src
// /home/user/projects/myapp/src/Main.java
// ...

// walk with maxDepth — 1 = direct children only, 2 = children + grandchildren
try (Stream<Path> shallow = Files.walk(root, 2)) {
    shallow.forEach(System.out::println);
}

// The start path (root) is ALWAYS the first element in the stream
// To exclude it: skip(1) or filter(p -> !p.equals(root))
try (Stream<Path> stream = Files.walk(root)) {
    stream.skip(1).forEach(System.out::println); // skip root itself
}

// Count all files and directories
try (Stream<Path> stream = Files.walk(root)) {
    long count = stream.count();
    System.out.println("Total entries: " + count);
}

// Collect all entries into a List
List<Path> allPaths;
try (Stream<Path> stream = Files.walk(root)) {
    allPaths = stream.collect(Collectors.toList());
}

// Total size of all files in a directory tree
long totalBytes;
try (Stream<Path> stream = Files.walk(root)) {
    totalBytes = stream
        .filter(Files::isRegularFile)
        .mapToLong(p -> {
            try { return Files.size(p); }
            catch (IOException e) { return 0L; }
        })
        .sum();
}
System.out.printf("Total size: %.2f MB%n", totalBytes / 1_048_576.0);
Always close the Stream returned by Files.walk(): it holds an open file handle to the directory. Failing to close it leaks the handle and may exhaust the OS file descriptor limit. Use try-with-resources every time.

Filtering with Stream operations

Because Files.walk() returns a standard Stream<Path>, any stream operation can be chained directly. Use filter() with Files.isRegularFile(), Files.isDirectory(), or extension checks on p.toString() to narrow results. When you need to filter on file attributes such as size or last-modified time, prefer Files.find() instead: it accepts a BiPredicate<Path, BasicFileAttributes> and reads attributes in a single OS call per file, avoiding the extra stat calls that Files.walk() + Files.size() would require.

Java
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;

Path root = Path.of("/home/user/projects");

// Find all .java source files
try (Stream<Path> stream = Files.walk(root)) {
    List<Path> javaFiles = stream
        .filter(Files::isRegularFile)
        .filter(p -> p.toString().endsWith(".java"))
        .collect(Collectors.toList());
    System.out.println("Java files: " + javaFiles.size());
}

// Find files modified in the last 24 hours
Instant oneDayAgo = Instant.now().minus(Duration.ofDays(1));
try (Stream<Path> stream = Files.walk(root)) {
    stream.filter(Files::isRegularFile)
          .filter(p -> {
              try {
                  return Files.getLastModifiedTime(p).toInstant().isAfter(oneDayAgo);
              } catch (IOException e) { return false; }
          })
          .forEach(p -> System.out.println("Recent: " + p));
}

// Files.find() — walk + BiPredicate, more efficient than walk + filter
// The predicate receives (Path, BasicFileAttributes) — attributes already read
try (Stream<Path> found = Files.find(root, Integer.MAX_VALUE,
        (path, attrs) -> attrs.isRegularFile()
            && attrs.size() > 100_000  // files > 100 KB
            && path.getFileName().toString().endsWith(".log"))) {
    found.forEach(p -> System.out.println("Large log: " + p));
}

// Delete all .class files in target/
Path target = Path.of("target");
try (Stream<Path> stream = Files.walk(target)) {
    stream.filter(Files::isRegularFile)
          .filter(p -> p.toString().endsWith(".class"))
          .forEach(p -> {
              try { Files.delete(p); }
              catch (IOException e) { System.err.println("Cannot delete: " + p); }
          });
}

// Delete a directory tree (delete deepest files first)
try (Stream<Path> stream = Files.walk(target)) {
    stream.sorted(Comparator.reverseOrder()) // directories after their children
          .forEach(p -> {
              try { Files.deleteIfExists(p); }
              catch (IOException e) { System.err.println("Failed: " + p); }
          });
}
Prefer Files.find() over Files.walk() + filter() when you need to inspect file attributes (size, timestamps, type) in the filter. Files.find() reads attributes once per file as part of the walk, whereas Files.walk() + filter() requires separate Files.size() or Files.getLastModifiedTime() calls: each of which is a separate OS stat call.

Files.walkFileTree() with FileVisitor

Files.walkFileTree() gives fine-grained control over directory traversal through the FileVisitor interface, which provides four callbacks: preVisitDirectory fires before entering a directory, visitFile fires for each file, visitFileFailed handles per-file errors such as permission denied, and postVisitDirectory fires after all entries have been visited. Each callback returns a FileVisitResult that controls whether to continue, skip a subtree, skip siblings, or stop entirely. This is the right tool when you need to skip specific directories, terminate early on a match, or respond differently to files versus directories.

Java
import java.nio.file.*;
import java.nio.file.attribute.*;
import java.io.IOException;

// FileVisitor has 4 callbacks:
//   preVisitDirectory  — called before entering a directory
//   visitFile          — called for each file
//   visitFileFailed    — called when a file cannot be visited (e.g., permission denied)
//   postVisitDirectory — called after all entries in a directory have been visited

// SimpleFileVisitor provides default (CONTINUE) implementations
Files.walkFileTree(Path.of("/home/user/projects"), new SimpleFileVisitor<Path>() {

    @Override
    public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
        String name = dir.getFileName() == null ? "" : dir.getFileName().toString();
        // Skip .git, .svn, node_modules, build output
        if (name.equals(".git") || name.equals("node_modules") || name.equals("target")) {
            System.out.println("Skipping: " + dir);
            return FileVisitResult.SKIP_SUBTREE;
        }
        System.out.println("Entering: " + dir);
        return FileVisitResult.CONTINUE;
    }

    @Override
    public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
        System.out.printf("  File: %-50s  %,d bytes%n",
            file.getFileName(), attrs.size());
        return FileVisitResult.CONTINUE;
    }

    @Override
    public FileVisitResult visitFileFailed(Path file, IOException exc) {
        System.err.println("Cannot access: " + file + "  reason: " + exc.getMessage());
        return FileVisitResult.CONTINUE; // continue despite access error
    }

    @Override
    public FileVisitResult postVisitDirectory(Path dir, IOException exc) {
        if (exc != null) System.err.println("Error after visiting: " + dir);
        return FileVisitResult.CONTINUE;
    }
});

// FileVisitResult values:
//   CONTINUE      — keep walking
//   SKIP_SUBTREE  — skip this directory's children (only valid in preVisitDirectory)
//   SKIP_SIBLINGS — skip remaining entries in the current directory
//   TERMINATE     — stop the entire walk immediately

// Practical: find and return first matching file
class FileFinder extends SimpleFileVisitor<Path> {
    private final String target;
    Path found = null;

    FileFinder(String target) { this.target = target; }

    @Override
    public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
        if (file.getFileName().toString().equals(target)) {
            found = file;
            return FileVisitResult.TERMINATE; // stop as soon as found
        }
        return FileVisitResult.CONTINUE;
    }
}

FileFinder finder = new FileFinder("config.properties");
Files.walkFileTree(Path.of("."), finder);
System.out.println(finder.found != null ? "Found: " + finder.found : "Not found");

DirectoryStream for single-level listing

Files.newDirectoryStream() lists only the immediate children of a directory: it does not recurse into subdirectories. It returns entries lazily via an iterator, making it more memory-efficient than collecting all paths into a list up front, especially for directories with thousands of entries. The order of entries is filesystem-dependent and not guaranteed to be sorted. Like all NIO stream-based APIs, DirectoryStream implements Closeable and must be closed with try-with-resources.

Java
import java.nio.file.*;
import java.io.IOException;

// DirectoryStream — efficient single-level directory iteration (not recursive)
// More lightweight than Stream<Path> from Files.list() for large directories
// Must be closed (implements Closeable)

Path dir = Path.of("/home/user/downloads");

try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
    for (Path entry : stream) {
        System.out.println(entry.getFileName());
    }
}

// Order is NOT guaranteed — depends on the OS and filesystem

// Filter: only regular files
try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
    for (Path entry : stream) {
        if (Files.isRegularFile(entry)) {
            System.out.printf("File: %s  (%,d bytes)%n",
                entry.getFileName(), Files.size(entry));
        }
    }
}

// Collect to a sorted list
List<Path> sorted;
try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
    sorted = new ArrayList<>();
    for (Path p : stream) sorted.add(p);
}
sorted.sort(Comparator.comparing(p -> p.getFileName().toString()));
sorted.forEach(System.out::println);

// DirectoryStream with a DirectoryStream.Filter — custom predicate
DirectoryStream.Filter<Path> filter = entry ->
    Files.isRegularFile(entry) && Files.size(entry) > 1_000_000; // > 1 MB

try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, filter)) {
    for (Path entry : stream) {
        System.out.println("Large file: " + entry.getFileName());
    }
}

DirectoryStream with glob filter

An overload of Files.newDirectoryStream() accepts a glob pattern string that filters entries before they are returned, avoiding the need for a separate filter step. Glob syntax uses * to match any sequence of characters within a single name component, ? to match exactly one character, [...] for character classes, and {a,b} for alternatives, for example "*.{txt,csv}" matches all text and CSV files. Note that * does not cross the path separator; use PathMatcher with Files.walk() and the ** glob segment when you need to match across multiple directory levels.

Java
// Files.newDirectoryStream(dir, glob) — glob pattern for single-level listing
// Glob syntax (not regex!):
//   *    — matches any string not containing /
//   **   — matches any string including / (for path matching)
//   ?    — matches any single character
//   [ab] — matches 'a' or 'b'
//   {a,b}— matches 'a' or 'b' (alternative)

Path dir = Path.of("/home/user/documents");

// All .pdf files in the directory
try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.pdf")) {
    for (Path p : stream) {
        System.out.println(p.getFileName());
    }
}

// All files matching multiple extensions
try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{jpg,jpeg,png,gif}")) {
    for (Path p : stream) {
        System.out.println("Image: " + p.getFileName());
    }
}

// Files starting with "report_"
try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "report_*")) {
    for (Path p : stream) {
        System.out.println(p.getFileName());
    }
}

// Using PathMatcher with glob for deep matching (Files.walk + PathMatcher)
PathMatcher matcher = FileSystems.getDefault()
    .getPathMatcher("glob:**/*.{java,kt}"); // any .java or .kt file, any depth

try (Stream<Path> walk = Files.walk(Path.of("src"))) {
    walk.filter(matcher::matches)
        .forEach(System.out::println);
}

// Glob vs regex — glob is simpler but less powerful
// Use glob for file-extension and name-pattern matching
// Use regex (Pattern) for complex content or path structure matching

// Check if a single path matches a glob
PathMatcher javaMatch = FileSystems.getDefault().getPathMatcher("glob:*.java");
System.out.println(javaMatch.matches(Path.of("Main.java"))); // true
System.out.println(javaMatch.matches(Path.of("Main.class"))); // false

Note: The glob delimiter * does not match the path separator /. To match across directory separators use **. For example, glob:**/*.java matches any .java file at any depth, while glob:*.java only matches in the directory being searched.

Files.list() vs Files.walk()

Files.list() is essentially Files.walk() with maxDepth=1: it returns a Stream<Path> of the immediate children of a directory without recursing. Both return lazy streams that must be closed. Choose Files.list() when you only need one level (equivalent to ls), Files.walk() when you need all descendants, and DirectoryStream when you need the most memory-efficient single-level iteration without the stream API overhead.

Java
import java.nio.file.*;

Path dir = Path.of("/home/user/projects");

// Files.list(dir) — non-recursive, single level, returns Stream<Path>
// Equivalent to DirectoryStream but as a Stream
try (Stream<Path> stream = Files.list(dir)) {
    stream.filter(Files::isDirectory)
          .map(Path::getFileName)
          .sorted()
          .forEach(System.out::println);
}

// Files.walk(dir) — recursive, depth-first, all descendants
try (Stream<Path> stream = Files.walk(dir)) {
    stream.filter(Files::isRegularFile)
          .forEach(System.out::println);
}

// Comparison:
// ┌──────────────────┬──────────────┬──────────────────────────────────┐
// │ API              │ Recursive?   │ Best for                         │
// ├──────────────────┼──────────────┼──────────────────────────────────┤
// │ Files.list()     │ No  (1 level)│ ls equivalent, simple listing    │
// │ DirectoryStream  │ No  (1 level)│ Memory-efficient iteration        │
// │ Files.walk()     │ Yes          │ Stream pipeline over all files    │
// │ Files.find()     │ Yes          │ Walk + attribute filter in one    │
// │ walkFileTree()   │ Yes          │ Precise control, skip subtrees    │
// └──────────────────┴──────────────┴──────────────────────────────────┘

// Practical: list only immediate subdirectories
try (Stream<Path> stream = Files.list(dir)) {
    List<String> subdirs = stream
        .filter(Files::isDirectory)
        .map(p -> p.getFileName().toString())
        .sorted()
        .collect(Collectors.toList());
    System.out.println("Subdirectories: " + subdirs);
}

// Practical: count files per extension recursively
try (Stream<Path> stream = Files.walk(dir)) {
    Map<String, Long> byExt = stream
        .filter(Files::isRegularFile)
        .collect(Collectors.groupingBy(
            p -> {
                String name = p.getFileName().toString();
                int dot = name.lastIndexOf('.');
                return dot >= 0 ? name.substring(dot) : "(no ext)";
            },
            Collectors.counting()
        ));
    byExt.entrySet().stream()
         .sorted(Map.Entry.<String, Long>comparingByValue().reversed())
         .forEach(e -> System.out.printf("%-15s %,d%n", e.getKey(), e.getValue()));
}

Handling symbolic links and cycles

By default, Files.walk() does not follow symbolic links: symlinked directories appear as entries but their contents are not traversed, making cycles impossible. To follow symlinks, pass FileVisitOption.FOLLOW_LINKS; if the walk encounters a directory it has already visited via a symlink, it throws a FileSystemLoopException. When using Files.walkFileTree() with FOLLOW_LINKS, handle FileSystemLoopException in visitFileFailed and return FileVisitResult.CONTINUE to skip the cycle rather than aborting the entire walk.

Java
import java.nio.file.*;

// By default, Files.walk() does NOT follow symbolic links
// This prevents infinite loops from symlink cycles

Path root = Path.of("/home/user/projects");

// Default — symlinks are listed as symlinks but NOT followed
try (Stream<Path> stream = Files.walk(root)) {
    stream.filter(Files::isSymbolicLink)
          .forEach(p -> System.out.println("Symlink: " + p));
}

// Follow symlinks — use FileVisitOption.FOLLOW_LINKS
// If a cycle is detected, a FileSystemLoopException is reported via visitFileFailed
try (Stream<Path> stream = Files.walk(root, FileVisitOption.FOLLOW_LINKS)) {
    stream.filter(Files::isRegularFile)
          .forEach(System.out::println);
}
// May throw FileSystemLoopException if a cycle exists

// walkFileTree with FOLLOW_LINKS — handle cycle in visitFileFailed
Files.walkFileTree(root,
    EnumSet.of(FileVisitOption.FOLLOW_LINKS),
    Integer.MAX_VALUE,
    new SimpleFileVisitor<Path>() {
        @Override
        public FileVisitResult visitFileFailed(Path file, IOException exc) {
            if (exc instanceof FileSystemLoopException) {
                System.err.println("Cycle detected: " + file);
                return FileVisitResult.CONTINUE; // skip the cycle
            }
            System.err.println("Cannot visit: " + file + " — " + exc);
            return FileVisitResult.CONTINUE;
        }

        @Override
        public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
            System.out.println(file);
            return FileVisitResult.CONTINUE;
        }
    });

// Detect symlinks and resolve them
Path link = Path.of("/home/user/projects/current");
if (Files.isSymbolicLink(link)) {
    Path target = Files.readSymbolicLink(link);
    Path resolved = link.getParent().resolve(target).normalize();
    System.out.println(link + " → " + resolved);
}

// Real path — resolves all symlinks in the path
Path real = link.toRealPath(); // throws NoSuchFileException if broken symlink
System.out.println("Real path: " + real);

// toRealPath without following links (Java has no direct option — use toAbsolutePath().normalize())
Path abs = link.toAbsolutePath().normalize(); // normalizes .. but does NOT resolve symlinks
Only use FileVisitOption.FOLLOW_LINKS when you explicitly need to traverse into symlinked directories. Without it, directory cycles are impossible because the walk never follows symlinks into directories it has already visited. With it, always handle FileSystemLoopException in visitFileFailed, otherwise the walk throws and stops.

Related articles

All Java articles →
Java NIO.2 Path and Files API: Modern File I/OJava NIO.2 Path and Files API: modern file I/O with Path, Files.readString, Files.writeString, walk, find, copy, move, and file attributes.Reading large files in Java efficientlyReading large files in Java efficiently. Discussion on how to read, write and process large files in Java efficiently interms of memory and CPU.Writing a text file in JavaHow to write a text file in Java with Files.writeString, Files.write, BufferedWriter and FileWriter, with examples.Properties Files: Reading and Writing .propertiesJava Properties Files: reading and writing .properties files, getProperty with defaults, XML properties, system properties, and Properties vs Map.