# is-safe-filename

> Check if a filename is safe to use in a path join operation

Latest version **0.1.1** (published 2026-01-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install is-safe-filename
pnpm add is-safe-filename
yarn add is-safe-filename
bun add is-safe-filename
```

## Health

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

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

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-01-25 |
| First published | 2026-01-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 5.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 15 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | filename, safe, secure, path, traversal, security, validate, check, local |

## Links

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

## 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

- 0.1.1 (latest) — 2026-01-25
- 0.1.0 — 2026-01-24

## README

# is-safe-filename

> Check if a filename is safe to use in a path join operation

A safe filename is one that won't escape the intended directory via path traversal.

This is a purely lexical check. It does not account for symlinks that may exist on the filesystem.

## Install

```sh
npm install is-safe-filename
```

## Usage

```js
import isSafeFilename from 'is-safe-filename';

isSafeFilename('foo');
//=> true

isSafeFilename('../foo');
//=> false

isSafeFilename('foo/bar');
//=> false
```

## API

### isSafeFilename(filename)

Returns `true` if the filename is safe.

### assertSafeFilename(filename)

Throws an error if the filename is not safe.

```js
import {assertSafeFilename} from 'is-safe-filename';

assertSafeFilename('foo');
// No error

assertSafeFilename('../foo');
//=> Error: Unsafe filename: "../foo"
```

### unsafeFilenameFixtures

A list of common unsafe filename fixtures for testing path traversal vulnerabilities.

Useful for testing that your code properly rejects unsafe filenames.

```js
import {unsafeFilenameFixtures} from 'is-safe-filename';

for (const filename of unsafeFilenameFixtures) {
	assert.throws(() => myFunction(filename));
}
```

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