# find-up

> Find a file or directory by walking up parent directories

Latest version **8.0.0** (published 2025-09-16) · MIT license · 0 weekly downloads

> **Better alternative:** See documentation for alternatives (https://github.com/AikidoSec/module-replacements/blob/main/docs/find-up)

## Install

```sh
npm install find-up
pnpm add find-up
yarn add find-up
bun add find-up
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 8.0.0 |
| Published | 2025-09-16 |
| First published | 2015-09-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 2 |
| Unpacked size | 23.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 643 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | find, up, find-up, findup, look-up, look, file, search, match, package, resolve, parent, parents, folder, directory, walk, walking, path |

## Links

- npm: https://www.npmjs.com/package/find-up
- Repository: https://github.com/sindresorhus/find-up
- Homepage: https://github.com/sindresorhus/find-up#readme
- Issues: https://github.com/sindresorhus/find-up/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/find-up

## Dependencies (2)

- [locate-path](https://npm.io/package/locate-path.md) ^8.0.0
- [unicorn-magic](https://npm.io/package/unicorn-magic.md) ^0.3.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 8.0.0 (latest) — 2025-09-16
- 7.0.0 — 2023-11-16
- 6.3.0 — 2022-02-08
- 6.2.0 — 2021-10-07
- 6.1.0 — 2021-09-26
- 6.0.0 — 2021-08-26
- 5.0.0 — 2020-08-11
- 4.1.0 — 2019-06-17
- 4.0.0 — 2019-05-12
- 3.0.0 — 2018-06-18
- 2.1.0 — 2016-12-02
- 2.0.0 — 2016-09-20
- 1.1.2 — 2016-03-05
- 1.1.1 — 2016-03-02
- 1.1.0 — 2015-11-14
- … 1 more at https://npm.io/package/find-up/versions

## README

# find-up

> Find a file or directory by walking up parent directories or down descendant directories

## Install

```sh
npm install find-up
```

## Usage

```
/
└── Users
    └── sindresorhus
        ├── unicorn.png
        └── foo
            └── bar
                ├── baz
                └── example.js
```

`example.js`

```js
import path from 'node:path';
import {pathExists} from 'path-exists';
import {findUp, findDown} from 'find-up';

console.log(await findUp('unicorn.png'));
//=> '/Users/sindresorhus/unicorn.png'

console.log(await findUp(['rainbow.png', 'unicorn.png']));
//=> '/Users/sindresorhus/unicorn.png'

console.log(await findUp(async directory => {
	const hasUnicorn = await pathExists(path.join(directory, 'unicorn.png'));
	return hasUnicorn && directory;
}, {type: 'directory'}));
//=> '/Users/sindresorhus'

// Find .git (could be a file or directory, common in submodules)
console.log(await findUp('.git', {type: 'both'}));
//=> '/Users/sindresorhus/.git'
```

## API

### findUp(name, options?)
### findUp(matcher, options?)

Returns a `Promise` for either the path or `undefined` if it could not be found.

### findUp([...name], options?)

Returns a `Promise` for either the first path found (by respecting the order of names) or `undefined` if none could be found.

### findUpMultiple(name, options?)
### findUpMultiple(matcher, options?)

Returns a `Promise` for either an array of all paths found or an empty array if none could be found.

**Note:** You can limit the number of matches by setting the `limit` option.

### findUpMultiple([...name], options?)

Returns a `Promise` for either an array of all paths found (by respecting the order of names) or an empty array if none could be found.

**Note:** You can limit the number of matches by setting the `limit` option.

### findUpSync(name, options?)
### findUpSync(matcher, options?)

Returns a path or `undefined` if it could not be found.

### findUpSync([...name], options?)

Returns the first path found (by respecting the order of names) or `undefined` if none could be found.

### findUpMultipleSync(name, options?)
### findUpMultipleSync(matcher, options?)

Returns an array of all paths found or an empty array if none could be found.

### findUpMultipleSync([...name], options?)

Returns an array of all paths found (by respecting the order of names) or an empty array if none could be found.

**Note:** You can limit the number of matches by setting the `limit` option.

### findDown(name, options?)
### findDown([...name], options?)

Find a file or directory by walking down descendant directories from `cwd`.

Returns a `Promise` for either the path or `undefined` if it could not be found.

```js
import {findUp, findDown} from 'find-up';

// Find the nearest parent directory that contains a specific file
// in its direct children (useful for monorepo roots)
console.log(await findUp(async directory => {
	return findDown('example.js', {cwd: directory, depth: 1});
}));
//=> '/Users/sindresorhus/foo'
```

### findDownSync(name, options?)
### findDownSync([...name], options?)

Synchronous version of `findDown`.

Returns the path or `undefined` if it could not be found.

#### name

Type: `string`

The name of the file or directory to find. Can be an array of names to search for multiple files.

#### matcher

Type: `Function`

Called for each directory in the search. Return a path or `findUpStop` to stop the search. Useful if you want to match files with certain patterns, set of permissions, or other advanced use-cases.

#### options

Type: `object`

##### cwd

Type: `URL | string`\
Default: `process.cwd()`

The directory to start from.

##### type

Type: `string`\
Default: `'file'`\
Values: `'file' | 'directory' | 'both'`

The type of path to match.

##### allowSymlinks

Type: `boolean`\
Default: `true`

Allow symbolic links to match if they point to the chosen path type.

##### stopAt

*Only for `findUp` functions*

Type: `URL | string`\
Default: Root directory

A directory path where the search halts if no matches are found before reaching this point.

##### limit

*Only for `findUpMultiple` and `findUpMultipleSync`*

Type: `number`\
Default: `Infinity`

The maximum number of matches to return. Useful for limiting results when searching for multiple files.

### findUpStop

A [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) that can be returned by a `matcher` function to stop the search and cause `findUp` to immediately return `undefined`. Useful as a performance optimization in case the current working directory is deeply nested in the filesystem.

```js
import path from 'node:path';
import {findUp, findUpStop} from 'find-up';

await findUp(directory => {
	// Stop searching if we've reached a 'work' directory
	if (path.basename(directory) === 'work') {
		return findUpStop;
	}

	// Look for package.json in this directory
	return 'package.json';
});
```

### findDown options

Type: `object`

##### cwd

Type: `URL | string`\
Default: `process.cwd()`

The directory to start from.

##### depth

Type: `number`\
Default: `1`

Maximum number of directory levels to traverse below `cwd`.

##### type

Type: `string`\
Default: `'file'`\
Values: `'file' | 'directory' | 'both'`

The type of path to match.

##### allowSymlinks

Type: `boolean`\
Default: `true`

Allow symbolic links to match if they point to the chosen path type.

##### strategy

Type: `string`\
Default: `'breadth'`\
Values: `'breadth' | 'depth'`

Search strategy to use:
- `'breadth'`: Breadth-first search, finds shallower matches first.
- `'depth'`: Depth-first search, fully explores each branch before moving to the next.

## Related

- [find-up-cli](https://github.com/sindresorhus/find-up-cli) - CLI for this module
- [package-up](https://github.com/sindresorhus/package-up) - Find the closest package.json file
- [package-directory](https://github.com/sindresorhus/package-directory) - Find the root directory of an npm package
- [resolve-from](https://github.com/sindresorhus/resolve-from) - Resolve the path of a module like `require.resolve()` but from a given path

---
_Source: https://npm.io/package/find-up · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._