# sanitize-filename

> Sanitize a string for use as a filename

Latest version **1.6.4** (published 2026-03-20) · WTFPL OR ISC license · 0 weekly downloads

## Install

```sh
npm install sanitize-filename
pnpm add sanitize-filename
yarn add sanitize-filename
bun add sanitize-filename
```

## Health

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

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

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.6.4 |
| Published | 2026-03-20 |
| First published | 2013-08-30 |
| Weekly downloads | 0 |
| License | WTFPL OR ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 17.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 370 |
| Author | Parsha Pourkhomami |
| Maintainers | parshap |
| Keywords | file, name, filename, sanitize, validate, escape |

## Links

- npm: https://www.npmjs.com/package/sanitize-filename
- Repository: https://github.com/parshap/node-sanitize-filename
- Homepage: https://github.com/parshap/node-sanitize-filename#readme
- Issues: https://github.com/parshap/node-sanitize-filename/issues
- npm.io page: https://npm.io/package/sanitize-filename

## Dependencies (1)

- [truncate-utf8-bytes](https://npm.io/package/truncate-utf8-bytes.md) ^1.0.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 1.6.4 (latest) — 2026-03-20
- 1.6.3 — 2019-08-26
- 1.6.2 — 2019-07-28
- 1.6.1 — 2016-09-29
- 1.6.0 — 2016-04-29
- 1.5.3 — 2015-11-09
- 1.5.2 — 2015-11-06
- 1.4.5 — 2015-10-10
- 1.4.4 — 2015-09-25
- 1.4.3 — 2015-09-11
- 1.4.2 — 2015-08-12
- 1.4.1 — 2015-07-31
- 1.4.0 — 2015-07-31
- 1.3.0 — 2015-03-24
- 1.2.0 — 2015-03-19
- … 8 more at https://npm.io/package/sanitize-filename/versions

## README

# sanitize-filename [![build status](https://secure.travis-ci.org/parshap/node-sanitize-filename.svg?branch=master)](http://travis-ci.org/parshap/node-sanitize-filename)

Sanitize a string to be safe for use as a filename by removing directory
paths and invalid characters.

## Install

[npm: *sanitize-filename*](https://www.npmjs.com/package/sanitize-filename)

```
npm install sanitize-filename
```

## Example

```js
var sanitize = require("sanitize-filename");

// Some string that may be unsafe or invalid as a filename
var UNSAFE_USER_INPUT = "~/.\u0000ssh/authorized_keys";

// Sanitize the string to be safe for use as a filename.
var filename = sanitize(UNSAFE_USER_INPUT);
// -> "~.sshauthorized_keys"
```

## Details

*sanitize-filename* removes the following:

 * [Control characters][] (`0x00`–`0x1f` and `0x80`–`0x9f`)
 * [Reserved characters][] (`/`, `?`, `<`, `>`, `\`, `:`, `*`, `|`, and
   `"`)
 * Unix reserved filenames (`.` and `..`)
 * Trailing periods and spaces ([for Windows][windows trailing])
 * Windows reserved filenames (`CON`, `PRN`, `AUX`, `NUL`, `COM1`,
   `COM2`, `COM3`, `COM4`, `COM5`, `COM6`, `COM7`, `COM8`, `COM9`,
   `LPT1`, `LPT2`, `LPT3`, `LPT4`, `LPT5`, `LPT6`, `LPT7`, `LPT8`, and
   `LPT9`)

[control characters]: https://en.wikipedia.org/wiki/C0_and_C1_control_codes
[reserved characters]: https://kb.acronis.com/content/39790
[windows trailing]: https://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx#Naming_Conventions

The resulting string is truncated to [255 bytes in length][255]. The
string will not contain any directory paths and will be safe to use as a
filename.

[255]: http://unix.stackexchange.com/questions/32795/what-is-the-maximum-allowed-filename-and-folder-size-with-ecryptfs

### Empty String `""` Result

An empty string `""` can be returned. For example:

```js
var sanitize = require("sanitize-filename");
sanitize("..")
// -> ""

```

### Non-unique Filenames

Two different inputs can return the same value. For example:

```js
var sanitize = require("sanitize-filename");
sanitize("file?")
// -> "file"
sanitize ("*file*")
// -> "file"
```

### File Systems

Sanitized filenames will be safe for use on modern Windows, OS X, and
Unix file systems (`NTFS`, `ext`, etc.).

[`FAT` 8.3 filenames][8.3] are not supported.

[8.3]: https://en.wikipedia.org/wiki/8.3_filename

#### Test Your File System

The test program will use various strings (including the [Big List of
Naughty Strings][blns]) to create files in the working directory. Run
`npm test` to run tests against your file system.

[blns]: https://github.com/minimaxir/big-list-of-naughty-strings

## API

### `sanitize(inputString, [options])`

Sanitize `inputString` by removing or replacing invalid characters.

Options:

 * `options.replacement`: *optional, string/function, default: `""`*. If passed
 as a string, it's used as the replacement for invalid characters. If passed as
 a function, the function will be called with the invalid characters and it's
 return value will be used as the replacement. See [`String.prototype.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
 for more info.

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