# gulp-rename

> Rename files

Latest version **2.1.0** (published 2025-06-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-rename
pnpm add gulp-rename
yarn add gulp-rename
bun add gulp-rename
```

## Health

**Score 33/100 (F)** — status: maintenance-mode.

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

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2025-06-26 |
| First published | 2013-12-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/gulp-rename) |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 0 |
| Unpacked size | 6.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 686 |
| Author | Hector Guillermo Parra Alvarez |
| Maintainers | hparra, fractal, shinnn, hgpa, yocontra |
| Keywords | gulpplugin |

## Links

- npm: https://www.npmjs.com/package/gulp-rename
- Repository: https://github.com/hparra/gulp-rename
- Issues: https://github.com/hparra/gulp-rename/issues
- npm.io page: https://npm.io/package/gulp-rename

## Recent versions

- 2.1.0 (latest) — 2025-06-26
- 2.0.0 — 2019-12-04
- 1.4.0 — 2018-07-23
- 1.3.0 — 2018-06-11
- 1.2.3 — 2018-05-15
- 1.2.2 — 2015-04-02
- 1.2.0 — 2014-03-06
- 1.1.0 — 2014-02-17
- 1.0.0 — 2014-02-07
- 0.2.2 — 2014-01-15
- 0.2.1 — 2013-12-08
- 0.1.0 — 2013-12-04

## README

# gulp-rename

gulp-rename is a [gulp](https://github.com/wearefractal/gulp) plugin to rename files easily.

[![NPM](https://nodei.co/npm/gulp-rename.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/gulp-rename/)

[![CI](https://github.com/hparra/gulp-rename/actions/workflows/ci.yml/badge.svg?branch=master)](http://travis-ci.org/hparra/gulp-rename)
[![NPM VERSION](https://img.shields.io/npm/v/gulp-rename.svg?sanitize=true)](https://www.npmjs.com/package/gulp-rename)

## Usage

gulp-rename provides simple file renaming methods.

```javascript
var rename = require("gulp-rename");

// rename to a fixed value
gulp.src("./src/main/text/hello.txt")
  .pipe(rename("main/text/ciao/goodbye.md"))
  .pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/goodbye.md

// rename via mutating function
gulp.src("./src/**/hello.txt")
  .pipe(rename(function (path) {
    // Updates the object in-place
    path.dirname += "/ciao";
    path.basename += "-goodbye";
    path.extname = ".md";
  }))
  .pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/hello-goodbye.md

// rename via a map function
gulp.src("./src/**/hello.txt")
  .pipe(rename(function (path) {
    // Returns a completely new object, make sure you return all keys needed!
    return {
      dirname: path.dirname + "/ciao",
      basename: path.basename + "-goodbye",
      extname: ".md"
    };
  }))
  .pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/hello-goodbye.md

// rename via a fixed object
gulp.src("./src/main/text/hello.txt", { base: process.cwd() })
  .pipe(rename({
    dirname: "main/text/ciao",
    basename: "aloha",
    prefix: "bonjour-",
    suffix: "-hola",
    extname: ".md"
  }))
  .pipe(gulp.dest("./dist")); // ./dist/main/text/ciao/bonjour-aloha-hola.md
```

**See [test/rename.spec.js](test/rename.spec.js) for more examples and [test/path-parsing.spec.js](test/path-parsing.spec.js) for hairy details.**

## Notes

* `dirname` is the relative path from the base directory set by `gulp.src` to the filename.
  * `gulp.src()` uses glob-stream which sets the base to the parent of the first directory glob (`*`, `**`, [], or extglob). `dirname` is the remaining directories or `./` if none. glob-stream versions >= 3.1.0 (used by gulp >= 3.2.2) accept a `base` option, which can be used to explicitly set the base.
  * `gulp.dest()` renames the directories between `process.cwd()` and `dirname` (i.e. the base relative to CWD). Use `dirname` to rename the directories matched by the glob or descendents of the base of option.
* `basename` is the filename without the extension like `path.basename(filename, path.extname(filename))`.
* `extname` is the file extension including the `.` like `path.extname(filename)`.
* when using a function, a second `file` argument is provided with the whole context and original file value.
* when using a function, if no `Object` is returned then the passed parameter object (along with any modifications) is re-used.

## License

[MIT License](http://en.wikipedia.org/wiki/MIT_License)

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