---
name: "watchfiles"
section: "1"
platform: "linux"
package: "python3-watchfiles"
version: "0.24.0-1+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/watchfiles"
---

# watchfiles(1)

Simple, modern and high performance file watching

## NAME

watchfiles - Simple, modern and high performance file watching

## SYNOPSIS

watchfiles \[**--ignore-paths** *\<IGNORE\_PATHS\>*\] \[**--target-type** (*command* \| *function* \| *auto*)\] \[**--filter** *\<FILTER\>*\] \[**--args** *\<ARGS\>*\] \[**--verbose\]** \[**--non-recursive**\] \[**--verbosity** (*warning* \| *info* \| *debug*)\] \[**--sigint-timeout** *\<SIGINT\_TIMEOUT\>*\] \[**--grace-period** *\<GRACE\_PERIOD\>*\] \[**--sigkill-timeout** *\<SIGKILL\_TIMEOUT\>*\] \[**--ignore-permission-denied**\] *target* \[*paths* ...\]

```
watchfiles (-h | --help)
watchfiles (-V | --version)
```

## DESCRIPTION

*watchfiles* watches one or more directories and executes either a Shell command or a Python function on file changes.

## ARGUMENTS

```
target  Command or dotted function path to run
paths   Filesystem paths to watch, defaults to current directory
```

## OPTIONS

```
-h | --help
Show this help message and exit
```

```
--ignore-paths <IGNORE_PATHS>
Specify directories to ignore, to ignore multiple paths use a comma as
separator, e.g. "env" or "env,node_modules"
```

```
--target-type (command | function | auto)
Whether the target should be intercepted as a shell command or a Python
function, defaults to "auto" which infers the target type from the target
string
```

```
--filter <FILTER>
Which files to watch, defaults to "default" which uses the
"DefaultFilter", "python" uses the "PythonFilter", "all" uses no filter,
any other value is interpreted as a Python function/class path which is
imported
```

```
--args <ARGS>
Arguments to set on sys.argv before calling target function, used only if
the target is a function
```

```
--verbose
Set log level to "debug", wins over --verbosity
```

```
--non-recursive
Do not watch for changes in sub-directories recursively
```

```
--verbosity (warning | info | debug)
Log level, defaults to "info"
```

```
--sigint-timeout <SIGINT_TIMEOUT>
How long to wait for the sigint timeout before sending sigkill.
```

```
--grace-period <GRACE_PERIOD>
Number of seconds after the process is started before watching for
changes.
```

```
--sigkill-timeout <SIGKILL_TIMEOUT>
How long to wait for the sigkill timeout before issuing a timeout
exception.
```

```
--ignore-permission-denied
Ignore permission denied errors while watching files and directories.
```

```
-V | --version
Show program's version number and exit
```

## EXAMPLES

Watching the current directory and calling a Python function:

$ watchfiles foobar.main

Watching Python files in two local directories and calling a Shell command:

$ watchfiles --filter python 'pytest --lf' src tests

## BUGS

Bugs can be reported to your distribution's bug tracker or upstream at  \<https://github.com/samuelcolvin/watchfiles/issues\>

## AUTHOR

Louis-Philippe Véronneau