# cp-file

> Copy a file

Latest version **11.0.0** (published 2023-11-05) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install cp-file
pnpm add cp-file
yarn add cp-file
bun add cp-file
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 11.0.0 |
| Published | 2023-11-05 |
| First published | 2014-06-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=14.16 |
| Dependencies | 3 |
| Unpacked size | 12.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 122 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | copy, cp, file, clone, fs, stream, file-system, ncp, fast, quick, data, content, contents |

## Links

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

## Dependencies (3)

- [p-event](https://npm.io/package/p-event.md) ^5.0.1
- [graceful-fs](https://npm.io/package/graceful-fs.md) ^4.2.10
- [nested-error-stacks](https://npm.io/package/nested-error-stacks.md) ^2.1.1

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

- 11.0.0 (latest) — 2023-11-05
- 10.0.0 — 2022-06-21
- 9.1.0 — 2021-06-13
- 9.0.0 — 2020-03-05
- 8.0.1 — 2020-02-24
- 8.0.0 — 2020-02-24
- 7.0.0 — 2019-04-19
- 6.2.0 — 2019-04-04
- 6.1.0 — 2019-03-04
- 6.0.0 — 2018-05-12
- 5.0.0 — 2017-09-22
- 4.2.0 — 2017-05-11
- 4.1.1 — 2016-11-25
- 4.1.0 — 2016-10-07
- 4.0.1 — 2016-10-03
- … 15 more at https://npm.io/package/cp-file/versions

## README

# cp-file

> Copy a file

## Highlights

- Fast by using streams in the async version and [`fs.copyFileSync()`](https://nodejs.org/api/fs.html#fs_fs_copyfilesync_src_dest_flags) in the synchronous version.
- Resilient by using [graceful-fs](https://github.com/isaacs/node-graceful-fs).
- User-friendly by creating non-existent destination directories for you.
- Can be safe by turning off [overwriting](#optionsoverwrite).
- Preserves file mode, [but not ownership](https://github.com/sindresorhus/cp-file/issues/22#issuecomment-502079547).
- User-friendly errors.

## Install

```sh
npm install cp-file
```

## Usage

```js
import {copyFile} from 'cp-file';

await copyFile('source/unicorn.png', 'destination/unicorn.png');
console.log('File copied');
```

## API

### copyFile(source, destination, options?)

Returns a `Promise` that resolves when the file is copied.

### copyFileSync(source, destination, options?)

#### source

Type: `string`

The file you want to copy.

#### destination

Type: `string`

Where you want the file copied.

#### options

Type: `object`

##### overwrite

Type: `boolean`\
Default: `true`

Overwrite existing destination file.

##### cwd

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

The working directory to find source files.

The source and destination path are relative to this.

##### directoryMode

Type: `number`\
Default: `0o777`

[Permissions](https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation) for created directories.

It has no effect on Windows.

##### onProgress

Type: `(progress: ProgressData) => void`

The given function is called whenever there is measurable progress.

Only available when using the async method.

###### `ProgressData`

```js
{
	sourcePath: string,
	destinationPath: string,
	size: number,
	writtenBytes: number,
	percent: number
}
```

- `sourcePath` and `destinationPath` are absolute paths.
- `size` and `writtenBytes` are in bytes.
- `percent` is a value between `0` and `1`.

###### Notes

- For empty files, the `onProgress` callback function is emitted only once.

```js
import {copyFile} from 'cp-file';

await copyFile(source, destination, {
	onProgress: progress => {
		// …
	}
});
```

## Related

- [cpy](https://github.com/sindresorhus/cpy) - Copy files
- [cpy-cli](https://github.com/sindresorhus/cpy-cli) - Copy files on the command-line
- [move-file](https://github.com/sindresorhus/move-file) - Move a file
- [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed

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