---
name: "File::Rename"
section: "3pm"
platform: "linux"
package: "rename"
version: "2.01-1"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/File::Rename"
---

# File::Rename(3pm)

Perl extension for renaming multiple files

## NAME

File::Rename - Perl extension for renaming multiple files

## SYNOPSIS

```
  use File::Rename qw(rename);          # hide CORE::rename
  rename \@ARGV, sub { s/\.pl\z/.pm/ }, 1;
  use File::Rename;
  File::Rename::rename \@ARGV, '$_ = lc';
  use File::Rename qw(:config no_require_order);
```

## DESCRIPTION

### USE OPTIONS

Parameters to `"use File::Rename"` consists of functions to be imported and configuration options.

The only exported function is `"rename()"`.  The configuation options are preceded by :config, and are passed to File::Rename::Options.

### FUNCTIONS

- "rename( FILES, CODE \[, VERBOSE\])"

  rename FILES using CODE, if FILES is empty read list of files from stdin

- "rename\_files( CODE, VERBOSE, FILES)"

  rename FILES using CODE

- "rename\_list( CODE, VERBOSE, HANDLE \[, FILENAME\])"

  rename a list of file read from HANDLE, using CODE

### OPTIONS

- FILES

  List of files to be renamed, for `"rename"` must be an ARRAY reference

- CODE

  Subroutine to change file names, for `"rename"` can be a string, otherwise it is a code reference

- VERBOSE

  Flag for printing names of files successfully renamed, optional for `"rename"`

- HANDLE

  Filehandle to read file names to be renames

- FILENAME (Optional)

  Name of file that HANDLE reads from

### HASH

Either CODE or VERBOSE can be a HASH of options.

If CODE is a HASH, VERBOSE is ignored  and CODE is supplied by the **\_code** key.

Other options are

- **verbose**

  As VERBOSE above, provided by **-v**.

- **input\_null**

  Input separator \\0 when reading file names from stdin.

- **no\_action**

  Print names of files to be renamed, but do not rename (i.e. take no action), provided by **-n**.

- **over\_write**

  Allow files to be over-written by the renaming, provided by **-f**.

- **filename\_only**

  Only apply renaming to the filename component of the path,  provided by **-d**.

- **show\_help**

  Print help, provided by **-h**.

- **show\_manual**

  Print manual page, provided by **-m**.

- **show\_version**

  Print version number, provided by **-V**.

- **unicode\_strings**

  Enable unicode\_strings feature, provided by **-u**.

- **encoding**

  Encoding for filenames, provided by **-u**.

### EXPORT

rename

## ENVIRONMENT

No environment variables are used.

## SEE ALSO

[**mv**(1)](/mv/1.md), [**perl**(1)](/perl/1.md), [**rename**(1)](/rename/1.md)

## AUTHOR

Robin Barker \<RMBarker@cpan.org\>

## Acknowledgements

Based on code from Larry Wall.

Options **-e**, **-f**, **-n** suggested by more recent code written by Aristotle Pagaltzis.

## DIAGNOSTICS

Errors from the code argument are not trapped.

## COPYRIGHT AND LICENSE

Copyright (C) 2004, 2005, 2006, 2011, 2018, 2021, 2022, 2023 by Robin Barker

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.