# Folders

*Estimated read time: 2 minutes*

You can run inference over a whole directory of images using `model.predict_dir(...)`.

## Signature

{% code overflow="wrap" %}

```python
degirum.model.Model.predict_dir(
    path, *, recursive=False,
    extensions=['.jpg', '.jpeg', '.png', '.bmp']
)
```

{% endcode %}

* **What it does**: runs the full inference lifecycle for all files in a folder that match the given extensions, yielding one `InferenceResults` per image
* **Returns**: an iterator (`Iterator[InferenceResults]`), so you can use it directly in a `for` loop
* **Limitations**: supports only single-input models

## Common setup (used in all cases)

{% code overflow="wrap" %}

```python
from pathlib import Path
from degirum_tools import ModelSpec

# Configure & load once
model_spec = ModelSpec(
    model_name="yolov8n_coco--640x640_quant_axelera_metis_1",
    zoo_url="degirum/axelera",
    inference_host_address="@local",  # or "@cloud" / server URL
    model_properties={"device_type": ["AXELERA/METIS"]},
)
model = model_spec.load_model()
```

{% endcode %}

{% hint style="info" %}
Most results include `result.image_overlay` (NumPy BGR), which you can save for quick visualization.
{% endhint %}

## Basic folder (non-recursive, default extensions)

Use when you have a flat folder of standard image formats.

{% code overflow="wrap" %}

```python
in_dir = Path("images")  # folder with .jpg/.jpeg/.png/.bmp

for result in model.predict_dir(str(in_dir)):
    # result contains detections & convenience fields like image_overlay
    print(result)  # optional: inspect structured output
```

{% endcode %}

## Nested folders (recursive walk)

Use when working with datasets split across subdirectories (e.g., class-based folders).

{% code overflow="wrap" %}

```python
in_dir = "datasets/val"  # root directory with subfolders

for result in model.predict_dir(in_dir, recursive=True):
    # handle/save each result as it arrives
    pass
```

{% endcode %}

{% hint style="info" %}

* **Iterator-friendly**: `predict_dir` streams results; you don’t load everything into memory.
* **Filtering**: Use `extensions=` (a string or list) to limit which files are processed.
* **Reproducibility**: Keep input folders immutable and write outputs to a separate directory.
* **Colorspace**: Overlay images are in BGR (OpenCV-ready). Convert to RGB on save/view if needed.
  {% endhint %}

## **Minimal example**

{% code overflow="wrap" %}

```python
for result in model.predict_dir("./some_path"):
    print(result)
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.degirum.com/axelera/basics/running-inference/folders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.