Skip to main content
File facts provide information about files, directories, and filesystem contents on target hosts.

File Information

File

Get detailed information about a single file or directory:
Parameters:
  • path (str, required) - Path to file or directory
Returns: dict | None - File information or None if file doesn’t exist Dict keys:
  • user (str) - Owner username
  • group (str) - Group name
  • mode (int) - Permissions as octal (e.g., 755)
  • size (int) - File size in bytes
  • mtime (datetime | None) - Modification time
  • atime (datetime | None) - Access time
  • ctime (datetime | None) - Change time
  • type (str) - File type: “file”, “directory”, “link”, “block”, “character”, “socket”, “fifo”
  • link_target (str | None) - Target path for symbolic links

Directory

Get list of files in a directory:
Parameters:
  • path (str, required) - Path to directory
Returns: list[str] | None - List of filenames, or None if directory doesn’t exist
Returns just filenames, not full paths. Use os.path.join() to build full paths.
Get the target of a symbolic link:
Parameters:
  • path (str, required) - Path to symbolic link
Returns: str | None - Target path, or None if not a link or doesn’t exist

File Contents

FindInFile

Search for a pattern in a file:
Parameters:
  • path (str, required) - Path to file
  • pattern (str, required) - Pattern to search for (plain text or regex)
Returns: list[str] | None - Matching lines, or None if file doesn’t exist

FindFiles

Find files matching a pattern:
Parameters:
  • path (str, required) - Directory to search in
  • pattern (str, required) - Filename pattern (glob style)
Returns: list[str] - List of matching file paths Find symbolic links in a directory:
Parameters:
  • path (str, required) - Directory to search
Returns: list[str] - List of symbolic link paths

FindDirectories

Find subdirectories:
Parameters:
  • path (str, required) - Directory to search
Returns: list[str] - List of subdirectory paths

File Hashes

Sha1File

Get SHA1 hash of a file:
Parameters:
  • path (str, required) - Path to file
Returns: str | None - SHA1 hash, or None if file doesn’t exist

Sha256File

Get SHA256 hash of a file:
Parameters:
  • path (str, required) - Path to file
Returns: str | None - SHA256 hash, or None if file doesn’t exist

Md5File

Get MD5 hash of a file:
Parameters:
  • path (str, required) - Path to file
Returns: str | None - MD5 hash, or None if file doesn’t exist

File System

BlockDevices

Get list of block devices:
Returns: list[str] - List of block device paths

DiskUsage

Get disk usage information:
Parameters:
  • path (str, required) - Path to check (file or directory)
Returns: dict - Disk usage information Dict keys:
  • filesystem (str) - Filesystem device
  • size (int) - Total size in bytes
  • used (int) - Used space in bytes
  • available (int) - Available space in bytes
  • used_percent (int) - Percentage used
  • mounted_on (str) - Mount point

Usage Examples

Check File Exists Before Creating

Check File Permissions

Find and Process Config Files

Search Config Files

Check Disk Space

Verify File Hash

List Directory Contents

Complete Example

Here’s a comprehensive example using file facts:

Source Reference

Location: src/pyinfra/facts/files.py

Key Facts

  • File - Get file information (line 138+)
  • Directory - List directory contents
  • Link - Get symlink target
  • FindInFile - Search file contents
  • FindFiles - Find files by pattern
  • Sha256File - Get file hash
  • DiskUsage - Get disk usage