# How the compare_faces Function Uses Tolerance to Match Faces in Python

> Learn how the compare_faces function in Python uses tolerance to accurately match faces. Understand Euclidean distances and the default tolerance of 0.6 for precise facial recognition.

- Repository: [Adam Geitgey/face_recognition](https://github.com/ageitgey/face_recognition)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The `compare_faces` function determines if a candidate face matches known faces by computing Euclidean distances and comparing them against a configurable `tolerance` threshold, defaulting to `0.6`.**

The `compare_faces` utility in the `ageitgey/face_recognition` library provides a simple boolean interface for face verification. According to the source code in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py), this function wraps lower-level distance calculations to return intuitive match results based on a similarity threshold you can adjust for strict or permissive matching.

## Understanding the compare_faces Algorithm

The implementation in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) (lines 217-226) follows a two-step process to determine matches.

### The Role of face_distance

First, `compare_faces` invokes **`face_distance`** to compute the Euclidean distance between the candidate face encoding and each known encoding. As implemented in lines 63-75 of [`api.py`](https://github.com/ageitgey/face_recognition/blob/main/api.py), this function uses NumPy's vector-norm operation to quantify facial similarity—smaller values indicate more similar faces.

### The Tolerance Threshold

Second, the function compares each computed distance against the **`tolerance`** parameter:

```python
distance <= tolerance

```

This comparison returns a list of boolean values, with `True` indicating that the specific known face is within the acceptable distance threshold of the candidate face.

## Tolerance Parameter Explained

The `tolerance` parameter acts as a similarity cutoff that directly controls the strictness of face matching.

### Default Value and Behavior

The default tolerance is **`0.6`**, a value empirically chosen to balance false positives and false negatives for general use cases. At this threshold, the function accepts faces that are reasonably similar while filtering out obvious mismatches.

### Adjusting Strictness

You can tune `tolerance` to match your application's security requirements:

- **Lower tolerance (e.g., `0.4`)**: Creates stricter matching suitable for authentication systems. The function only returns `True` when faces are very close in feature space, reducing the risk of false positives.
- **Higher tolerance (e.g., `0.8`)**: Enables more permissive matching for photo organization or similarity searches. This setting finds faces that share general characteristics even if they are not identical.

## Code Examples

### Basic Matching with Default Tolerance

This example demonstrates standard usage with the default `0.6` tolerance:

```python
import face_recognition

known_image = face_recognition.load_image_file("known.jpg")
unknown_image = face_recognition.load_image_file("unknown.jpg")

known_encodings = face_recognition.face_encodings(known_image)
unknown_encoding = face_recognition.face_encodings(unknown_image)[0]

matches = face_recognition.compare_faces(known_encodings, unknown_encoding)
print(matches)  # Output: [True] if within tolerance, [False] otherwise

```

### Stricter Verification for Security

For authentication scenarios, reduce the tolerance to minimize false positives:

```python

# Use strict tolerance of 0.45 for high-security matching

matches = face_recognition.compare_faces(
    known_encodings, 
    unknown_encoding, 
    tolerance=0.45
)

```

### Batch Processing with Permissive Matching

Process multiple unknown faces against a known set using a higher tolerance:

```python
unknown_images = ["u1.jpg", "u2.jpg", "u3.jpg"]
unknown_encodings = [
    face_recognition.face_encodings(face_recognition.load_image_file(f))[0]
    for f in unknown_images
]

# Permissive tolerance for finding similar faces

results = [
    face_recognition.compare_faces(known_encodings, enc, tolerance=0.75)
    for enc in unknown_encodings
]

for img, res in zip(unknown_images, results):
    print(f"{img}: {res}")

```

## Summary

- **`compare_faces`** in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) wraps Euclidean distance calculations to provide boolean face matching.
- The function uses **`face_distance`** (lines 63-75) to compute similarity metrics via NumPy vector operations.
- The **`tolerance`** parameter (default `0.6`) sets the maximum acceptable distance for a match.
- Lower tolerance values increase security by requiring closer feature space proximity, while higher values increase recall for similarity searches.

## Frequently Asked Questions

### What is the default tolerance value in compare_faces?

The default tolerance is **0.6**. This value is hardcoded in the function signature in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) and represents a balanced threshold that works well for general face recognition tasks without requiring calibration.

### How does lowering the tolerance affect face matching accuracy?

Lowering the tolerance makes the matching **more strict** and reduces false positives. When you set tolerance to `0.4` or `0.45`, the function only returns `True` when the Euclidean distance between face encodings is very small, meaning the faces must be nearly identical in the 128-dimensional feature space. This is ideal for security applications where accepting an impostor is costly.

### Can I use compare_faces for one-to-many matching?

Yes. The `known_face_encodings` parameter accepts a list of encodings, and the function returns a boolean list of the same length indicating which known faces match the candidate. This design supports efficient one-to-many verification where you compare one unknown face against a database of known faces in a single function call.

### What distance metric does compare_faces use internally?

The function uses **Euclidean distance** (L2 norm) computed via NumPy's vector norm operation. Specifically, `face_distance` in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) calculates `np.linalg.norm(known_encodings - face_encoding_to_check, axis=1)`, which measures the straight-line distance between 128-dimensional face embeddings. Smaller distances indicate higher similarity.