Dart FileStat

last modified October 18, 2026

The FileStat class in Dart provides file system statistics for files and directories. It's part of the dart:io library and offers metadata about file system entities.

FileStat includes information like file size, modification time, and type. It's useful for file management, synchronization, and monitoring operations.

Basic Definition

FileStat is an immutable class representing file system statistics. It's obtained through the FileSystemEntity.stat() method.

Key properties include type, size, and modification time. The class helps determine file existence, permissions, and other attributes without opening.

Getting Basic File Statistics

This example shows how to get basic file statistics using FileStat.

import 'dart:io';

void main() async {
  var file = File('example.txt');
  await file.writeAsString('Hello, Dart!');
  
  var stat = await file.stat();
  
  print('File type: ${stat.type}');
  print('File size: ${stat.size} bytes');
  print('Modified: ${stat.modified}');
}

We create a file, write some content, then retrieve its statistics. The stat method returns a Future<FileStat> with the file's metadata.

$ dart main.dart
File type: file
File size: 12 bytes
Modified: 2025-04-04 10:30:45.000

Checking File Existence

This example demonstrates using FileStat to check if a file exists.

import 'dart:io';

void main() async {
  var file = File('nonexistent.txt');
  
  var stat = await file.stat();
  if (stat.type == FileSystemEntityType.notFound) {
    print('File does not exist');
  } else {
    print('File exists');
  }
}

We attempt to get statistics for a non-existent file. The stat() method does not throw for a missing path; it completes with a FileStat whose type is FileSystemEntityType.notFound.

$ dart main.dart
File does not exist

Comparing File Modification Times

This example shows how to compare modification times of two files.

import 'dart:io';

void main() async {
  var file1 = File('file1.txt');
  var file2 = File('file2.txt');
  
  await file1.writeAsString('First file');
  await Future.delayed(Duration(seconds: 1));
  await file2.writeAsString('Second file');
  
  var stat1 = await file1.stat();
  var stat2 = await file2.stat();
  
  if (stat1.modified.isBefore(stat2.modified)) {
    print('file1 was modified before file2');
  } else {
    print('file2 was modified before file1');
  }
}

We create two files with a delay between them, then compare their modification times. This is useful for synchronization scenarios.

$ dart main.dart
file1 was modified before file2

Getting Directory Statistics

This example demonstrates getting statistics for a directory.

import 'dart:io';

void main() async {
  var dir = Directory('test_dir');
  await dir.create();
  
  var stat = await dir.stat();
  
  print('Type: ${stat.type}');
  print('Modified: ${stat.modified}');
  print('Size: ${stat.size}'); // Directories may report 0 size
}

We create a directory and retrieve its statistics. Note that directory sizes may report as 0 on some platforms, as they don't include contents.

$ dart main.dart
Type: directory
Modified: 2025-04-04 10:32:10.000
Size: 4096

Symbolic Link Statistics

This example shows how to get statistics for a symbolic link.

import 'dart:io';

void main() async {
  var file = File('target.txt');
  await file.writeAsString('Target file content');
  
  var link = Link('link.txt');
  await link.create(file.path);
  
  // Report the link itself rather than the entity it points to
  var type = await FileSystemEntity.type(link.path, followLinks: false);
  print('Link type: $type');
  print('Link target: ${await link.target()}');
  
  // Link.stat() follows the link and returns the target's statistics
  var targetStat = await link.stat();
  print('Target size: ${targetStat.size}');
  
  await link.delete();
  await file.delete();
}

We create a symbolic link and examine it. FileSystemEntity.type() accepts followLinks: false, which reports the link itself, while link.target() returns the path it points to. FileStat has no followLinks parameter: link.stat() always follows the link and returns statistics for the target.

$ dart main.dart
Link type: link
Link target: target.txt
Target size: 19

Best Practices

• Caching: Cache FileStat objects for frequently accessed files
• Error handling: Always handle potential IO exceptions
• Performance: Avoid unnecessary stat calls in performance-critical code
• Cross-platform: Be aware of platform differences in reported values

Source

Dart FileStat Documentation

This tutorial covered Dart's FileStat class with practical examples showing file metadata access, existence checks, and special cases like directories.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.