File Selection

By default, Syft catalogs file details and digests for files owned by discovered packages. You can change this behavior using the SYFT_FILE_METADATA_SELECTION environment variable or the file.metadata.selection configuration option.

Available options:

• all: capture all files from the search space
• owned-by-package: capture only files owned by packages (default)
• none: disable file information capture

Excluding file paths

You can exclude specific files and paths from scanning using glob patterns with the --exclude parameter. Use multiple --exclude flags to specify multiple patterns.

# Exclude a specific directory
syft <source> --exclude /etc

# Exclude files by pattern
syft <source> --exclude './out/**/*.json'

# Combine multiple exclusions
syft <source> --exclude './out/**/*.json' --exclude /etc --exclude '**/*.log'

syft <source> --exclude '**/*.json'  # Correct
syft <source> --exclude **/*.json    # May not work as expected

Exclusion behavior by source type

How Syft interprets exclusion patterns depends on whether you’re scanning an image or a directory.

Image scanning

When scanning container images, Syft scans the entire filesystem. Use absolute paths for exclusions:

# Exclude system directories
syft alpine:latest --exclude /etc --exclude /var

# Exclude files by pattern across entire filesystem
syft alpine:latest --exclude '/usr/**/*.txt'

Directory scanning

When scanning directories, Syft resolves exclusion patterns relative to the specified directory. All exclusion patterns must begin with ./, */, or **/.

# Scanning /usr/foo
syft /usr/foo --exclude ./package.json        # Excludes /usr/foo/package.json
syft /usr/foo --exclude '**/package.json'     # Excludes all package.json files under /usr/foo
syft /usr/foo --exclude './out/**'            # Excludes everything under /usr/foo/out

Path prefix requirements for directory scans:

Common exclusion patterns

# Exclude all JSON files
syft <source> --exclude '**/*.json'

# Exclude build output directories
syft <source> --exclude '**/dist/**' --exclude '**/build/**'

# Exclude dependency directories
syft <source> --exclude '**/node_modules/**' --exclude '**/vendor/**'

# Exclude test files
syft <source> --exclude '**/*_test.go' --exclude '**/test/**'

FAQ

Why is my exclusion pattern not working?

Common issues:

• Missing quotes: Wrap patterns in single quotes to prevent shell expansion ('**/*.json' not **/*.json)
• Wrong path prefix: Directory scans require ./, */, or **/ prefix; absolute paths like /etc won’t work
• Pattern syntax: Use glob syntax, not regex (e.g., **/*.txt not .*\.txt)

What’s the difference between owned-by-package and all file metadata?

• owned-by-package (default): Only catalogs files that belong to discovered packages (e.g., files in an RPM’s file manifest)
• all: Catalogs every file in the scan space, which significantly increases SBOM size and scan time

Use all when you need complete file listings for compliance or audit purposes.

Can I exclude directories based on .gitignore?

Not directly, but you can convert .gitignore patterns to --exclude flags. Note that .gitignore syntax differs from glob patterns, so you may need to adjust patterns (e.g., node_modules/ becomes **/node_modules/**).

Do exclusions affect package detection?

Yes! If you exclude a file that a cataloger needs (like package.json or requirements.txt), Syft won’t detect packages from that file. Exclude carefully to avoid missing dependencies.

Next steps

Additional resources:

• Configure catalogers: See Package Catalogers to control which package types are detected
• Configuration file: Use Configuration to set persistent exclusion patterns
• Scan target types: Review Supported Scan Targets to understand scanning behavior for different scan target types