---
title: "import.file | Grafana Agent documentation"
description: "Learn about the import.file configuration block"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# import.file

> **BETA**: This is a [beta](/docs/agent/next/stability/#beta) component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

The `import.file` block imports custom components from a file or a directory and exposes them to the importer. `import.file` blocks must be given a label that determines the namespace where custom components are exposed.

Imported directories are treated as single modules to support composability. That means that you can define a custom component in one file and use it in another custom component in another file in the same directory.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
import.file "NAMESPACE" {
  filename = PATH_NAME
}
```

## Arguments

The following arguments are supported:

Expand table

| Name             | Type       | Description                                         | Default      | Required |
|------------------|------------|-----------------------------------------------------|--------------|----------|
| `filename`       | `string`   | Path of the file or directory on disk to watch.     |              | yes      |
| `detector`       | `string`   | Which file change detector to use (fsnotify, poll). | `"fsnotify"` | no       |
| `poll_frequency` | `duration` | How often to poll for file changes.                 | `"1m"`       | no       |

### File change detectors

File change detectors detect when the file needs to be re-read from disk. `local.file` supports two detectors: `fsnotify` and `poll`.

#### fsnotify

The `fsnotify` detector subscribes to filesystem events, which indicate when the watched file is updated. This detector requires a filesystem that supports events at the operating system level. Network-based filesystems like NFS or FUSE won’t work.

The component re-reads the watched file when a filesystem event is received. This re-read happens for any filesystem event related to the file, including a permissions change.

`fsnotify` also polls for changes to the file with the configured `poll_frequency` as a fallback.

`fsnotify` stops receiving filesystem events if the watched file has been deleted, renamed, or moved. The subscription is re-established on the next poll once the watched file exists again.

#### poll

The `poll` file change detector causes the watched file to be re-read every `poll_frequency`, regardless of whether the file changed.

## Example

This example imports a module from a file and instantiates a custom component from the import that adds two numbers:

module.river

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}
```

importer.river

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
import.file "math" {
  filename = "module.river"
}

math.add "default" {
  a = 15
  b = 45
}
```