Skip to main content
SysAdmin Shell Scripting Essentials

Linux mv Command Reference – Syntax, Exit Codes, Troubleshooting

6 min read

Master the Linux mv command: syntax, flags, production examples, exit codes, troubleshooting. Expert guide for moving and renaming files without data duplication.

mv moves or renames files and directories without duplicating data; it updates directory entries atomically within the same filesystem.

mv [OPTION]... SOURCE DEST
mv [OPTION]... SOURCE... DIRECTORY

When the last operand names an existing directory, mv moves each source into that directory. Otherwise, it renames the single source to the destination name. The command never traverses filesystems automatically; if the destination is on a different filesystem, mv copies then deletes the source, preserving metadata where possible.

Tested on Ubuntu 22.04 with coreutils 8.32.

Options and Flags

Flag Type Default Description
-i Boolean Off Prompt before overwriting any existing destination file. Overrides -f.
-f Boolean Off Force overwrite: do not prompt even if destination is write‑protected. Overrides -i and -n.
-n Boolean Off No‑clobber: do not overwrite an existing destination. Overrides -i and -f.
-b Boolean Off Make a simple backup of each existing destination file before overwriting. Appends ~ by default; use --suffix to change.
-u Boolean Off Update: move only when the source is newer than the destination or when the destination is missing.
-v Boolean Off Verbose: print the name of each file as it is moved or renamed.
-S / --suffix String ~ Override the backup suffix (e.g., -S .bak).
--backup[=CONTROL] Enum Off Make a numbered or existing backup (none, numbered, existing, simple). Equivalent to -b combined with version control.
-t / --target-directory Path N/A Specify the target directory explicitly. Useful when using find pipelines.
--help Flag N/A Display help text and exit.
See also  linux show processes: ps command reference with examples

Usage Examples

Rename a file in-place

mv release-v2.3.tar.gz release-latest.tar.gz

Only the directory entry changes; the inode remains the same. The file content is not copied. This is the same operation as moving within a single filesystem.

Move multiple files to a directory with verbose output

mv -v config.yaml secrets.env scripts/ /opt/app/backup/

Each source is moved into the destination directory. The -v flag prints every rename path, useful during audits or cron job logging.

Safe move with backup

mv -b --suffix=.bak /etc/nginx/nginx.conf /etc/nginx/nginx.conf.old

If nginx.conf.old already exists, mv renames it to nginx.conf.old.bak before overwriting. The --suffix flag allows a custom extension. Avoids accidental data loss during configuration rollouts.

Troubleshooting & Common Errors

Error Message / Scenario Root Cause Resolution Command
mv: cannot stat 'source': No such file or directory Source path is incorrect or contains a typo. Verify with ls -la source. Use tab completion.
mv: cannot move 'file' to '/destination/file': Permission denied Lack of write permission on source or destination directory. Use sudo mv or chmod u+w destination_dir.
mv: overwrite '/dest/file' (y/n)? Default interactive mode in some aliases; or -i was used. Use mv -f to force overwrite, or mv -n to skip.
mv: cannot move 'file' to 'subdir/file': Invalid cross-device link Destination is on a different filesystem. This is normal; mv will copy and delete. To avoid copy, move within the same filesystem.
mv: missing file operand No source or destination provided. Check syntax: mv SOURCE DEST or mv SOURCE... DIRECTORY.

Closing Tip

Always pair mv with -i (or -n) in interactive scripts to prevent silent data loss, and reserve -f for non‑interactive automation where idempotent overwrite is the desired behavior.

Performance Considerations and Tuning

The mv command does not expose performance knobs such as buffer sizes, MTU, or parallelism flags. Tuning is achieved at the filesystem, mount, and job‑orchestration layers. For same‑filesystem moves, mv simply renames the directory entry and is nearly instant. Cross‑filesystem moves perform a copy followed by a delete, making them I/O‑bound. Key tuning areas include:

  • Filesystem mount options: For network file systems (NFS, CIFS), increase read/write buffers with options like rsize=1048576,wsize=1048576 and use TCP with proto=tcp,timeo=600. Check current settings with mount | grep /target. These mount flags are documented in man mount and Documentation/filesystems/nfs/nfs-mount.txt in the Linux kernel.
  • Parallelism for bulk moves: Combine find with xargs -P to move many files concurrently, which can saturate disk or network bandwidth. Example moves all .log files using 4 parallel workers:
find /source -type f -name "*.log" -print0 | xargs -0 -P 4 -I {} mv {} /target/
  • Metadata reduction: Use the noatime mount option to avoid updating access times on reads, reducing metadata I/O. This is described in Documentation/filesystems/ext4/ and the mount(8) man page.
  • Environment variables: While VERSION_CONTROL and SIMPLE_BACKUP_SUFFIX affect backup behavior, they do not improve throughput.
See also  chown Unix Command: Syntax, Flags, and Troubleshooting

For cross‑filesystem moves, consider using rsync --remove-source-files with options like --bwlimit=RATE for traffic control; however, this goes beyond the native mv command. Always verify mount settings with mount and tune at the kernel or filesystem level for optimal mv performance.

Frequently Asked Questions

What is the difference between mv -i and mv -f?

mv -i prompts before overwriting destination; mv -f forces overwrite without prompting. The -i (interactive) flag protects against accidental data loss by asking confirmation before overwriting. -f (force) suppresses all prompts, overriding any restrictive permissions on the destination. For idempotent automation, -f is preferred; for manual operations, -i adds a safeguard.

mv -i source.txt /dest/   # prompts if /dest/source.txt exists
mv -f source.txt /dest/   # overwrites without question

When should I use the -u flag with mv?

Use -u (update) to move only when source is newer than destination or destination is missing. The -u flag performs a timestamp comparison: the source file replaces the destination only if the source’s modification time is later. If the destination does not exist, the move proceeds regardless. This is ideal for incremental backup scripts or syncing directories without overwriting recently changed target files.

mv -u logs/current.log archive/   # only moves if current.log is newer

How do I fix “cannot move (Device or resource busy)” error?

Run lsof /path/to/file to identify the process holding the file. This error occurs when the file is opened by another process (e.g., a running binary or a log file held by systemd) or when the mount point is busy. Use lsof to list open file descriptors, then terminate the blocking process with kill -9 . For filesystems, umount -l /path may force-lazy unmount.

lsof /data/busyfile
kill -9 1234
mv /data/busyfile /backup/

Does mv work on AWS EC2, Azure VMs, and GCP Compute Engine?

Yes, mv is part of GNU coreutils, standard on all Linux distributions used on AWS, Azure, and GCP compute instances. The mv command is a POSIX-required utility bundled with every major Linux distribution (Ubuntu, CentOS, Amazon Linux, Debian, RHEL, etc.). Whether deploying on EC2, Azure Virtual Machines, or GCP Compute Engine, mv is available by default with identical behavior. No additional installation or cloud-specific configuration is needed.

# Works identically across all cloud providers
mv /var/www/app /opt/backups/

What is the fastest way to rename a large number of files in a directory with mv?

For bulk renaming (e.g., adding a prefix or changing extensions), use a for loop or find with xargs -P for parallel moves. Avoid spawning one mv per file when possible to reduce fork overhead. Example using xargs for parallel moves:

find . -name '*.tmp' -print0 | xargs -0 -P 4 -I {} mv {} /tmp/archive/

Alternatively, for pattern-based renaming, the rename (Perl) utility is faster, but pure mv with find and xargs scales well.