1. Introduction

The cp command is a cornerstone of file management in Linux and Unix-like systems, enabling users to copy files and directories efficiently. Whether duplicating a configuration file, backing up data, or organizing project folders, cp offers the flexibility needed for these tasks. This guide provides a comprehensive overview of the cp command, structured to match the format of the ls and mv command guides. It includes detailed examples with a test directory setup, answers to popular questions from forums, and validation against the official GNU Coreutils documentation (cp(1) - Linux manual page ).

2. Basic Syntax

The cp command supports multiple syntax patterns for different copying scenarios:

2.1 Copy a single SOURCE to a DESTination file:

cp [OPTION]... SOURCE DEST

• If DEST is an existing file, it’s overwritten unless options like -i (interactive) or -n (no-clobber) are used.
• If DEST is a directory, SOURCE is copied into it with the same name.
• If DEST doesn’t exist, a new file is created.

2.2 Copy multiple SOURCE files into a DIRECTORY:

cp [OPTION]... SOURCE... DIRECTORY

• Copies all SOURCE files into an existing DIRECTORY.

2.3 Alternative syntax using -t:

cp [OPTION]... -t DIRECTORY SOURCE...

• Specifies the destination directory first, useful for scripts.

• [OPTION]...: Flags like -r (recursive) or -p (preserve attributes).

• SOURCE: File or directory to copy.

• DEST: Destination file or path.

• DIRECTORY: Target directory for multiple sources.

3. Key Options Explained (with Examples)

To demonstrate cp, let’s set up a test environment:

# Create and navigate to a test directory
mkdir cp_test_dir
cd cp_test_dir
 
# Create sample files
echo "This is file A." > fileA.txt
echo "This is file B." > fileB.log
touch empty_file
 
# Create a subdirectory with a file
mkdir subdir
echo "Subdir file." > subdir/sub_file.txt
 
# Create a symbolic link
ln -s fileB.log link_to_fileB
 
# Create a file with spaces in the name
echo "File with spaces." > "file with spaces.txt"
 
# Verify setup
ls -lR

Output:

.:
total 16
-rw-r--r-- 1 user user   0 May  4 18:54 empty_file
-rw-r--r-- 1 user user  16 May  4 18:54 fileA.txt
-rw-r--r-- 1 user user  16 May  4 18:54 fileB.log
-rw-r--r-- 1 user user  20 May  4 18:54 file with spaces.txt
lrwxrwxrwx 1 user user   9 May  4 18:54 link_to_fileB -> fileB.log
drwxr-xr-x 2 user user 4096 May  4 18:54 subdir

./subdir:
total 4
-rw-r--r-- 1 user user 13 May  4 18:54 sub_file.txt

3.1 Copying a Single File

Duplicate fileA.txt as fileA_copy.txt:

cp fileA.txt fileA_copy.txt
ls

Output:

empty_file  fileA_copy.txt  fileA.txt  fileB.log  file with spaces.txt  link_to_fileB  subdir

Explanation: The cp command creates fileA_copy.txt with the same content as fileA.txt. The directory now includes the new file.

3.2 Copying a File into a Directory

Copy fileB.log into subdir:

cp fileB.log subdir/
ls subdir/

Output:

fileB.log  sub_file.txt

Explanation: fileB.log is copied into subdir/, where it appears alongside sub_file.txt. The original file remains unchanged.

3.3 Copying Multiple Files into a Directory

Copy fileA.txt and empty_file into subdir:

cp fileA.txt empty_file subdir/
ls subdir/

Output:

empty_file  fileA.txt  fileB.log  sub_file.txt

Explanation: Both fileA.txt and empty_file are copied into subdir/, adding to its contents. The source files remain in the parent directory.

4. Key Options Explained (with Examples)

This section lists all key options, including advanced ones previously under “Advanced/Other Options”, with detailed examples using the test environment. Each example includes the command, output, and an explanation of the directory structure change.

4.1 -r, -R, —recursive: Copy directories recursively

• Description: Copies directories and their contents, including subdirectories and files, recursively.
• Example:

  cp -r subdir subdir_copy
  ls
  ls subdir_copy/

  Output:

  empty_file  fileA_copy.txt  fileA.txt  fileB.log  file with spaces.txt  link_to_fileB  subdir  subdir_copy
  empty_file  fileA.txt  fileB.log  sub_file.txt

  Explanation: The subdir directory, including all its files, is copied to subdir_copy. The new directory subdir_copy appears in the parent directory with identical contents.

4.2 -t, —target-directory=DIR: Copy all SOURCE arguments into DIR

• Description: Specifies the destination directory first, useful for scripts or when copying multiple files.
• Example:

  cp -t subdir_copy/ fileA.txt empty_file
  ls subdir_copy/

  Output:

  empty_file  fileA.txt  fileB.log  sub_file.txt

  Explanation: fileA.txt and empty_file are copied into subdir_copy/, adding to its existing contents. This syntax is equivalent to cp fileA.txt empty_file subdir_copy/.

4.3 -v, —verbose: Explain what is being done

• Description: Displays a message for each file copied, showing the source and destination.
• Example:

  cp -v fileA.txt fileA_verbose_copy.txt

  Output:

  'fileA.txt' -> 'fileA_verbose_copy.txt'

  Explanation: A new file fileA_verbose_copy.txt is created, and the verbose output confirms the copy operation. The parent directory now includes this new file.

4.4 -i, —interactive: Prompt before overwrite

• Description: Prompts for confirmation before overwriting an existing file, preventing accidental data loss.
• Example:

  # Ensure fileA.txt exists in subdir_copy
  cp fileA.txt subdir_copy/
  cp -i fileB.log subdir_copy/fileA.txt

  Output:

  cp: overwrite 'subdir_copy/fileA.txt'? y

  Explanation: The command prompts before overwriting subdir_copy/fileA.txt with fileB.log. If y is entered, fileA.txt in subdir_copy/ is replaced with fileB.log’s content; otherwise, it remains unchanged.

4.5 -n, —no-clobber: Do not overwrite existing files

• Description: Prevents overwriting existing files at the destination without prompting.
• Example:

  cp -n fileB.log subdir_copy/fileA.txt
  ls -l subdir_copy/fileA.txt

  Output:

  -rw-r--r-- 1 user user 16 May  4 18:54 subdir_copy/fileA.txt

  Explanation: Since fileA.txt exists in subdir_copy/, the -n option prevents fileB.log from overwriting it. The file subdir_copy/fileA.txt retains its original content.

4.6 -u, —update: Copy only when source is newer or destination is missing

• Description: Copies files only if the source is newer than the destination or if the destination does not exist.
• Example:

  # Set an older timestamp on subdir_copy/fileA.txt
  touch -t 202505040000 subdir_copy/fileA.txt
  cp -u fileA.txt subdir_copy/
  ls -l subdir_copy/fileA.txt

  Output:

  -rw-r--r-- 1 user user 16 May  4 18:54 subdir_copy/fileA.txt

  Explanation: Since fileA.txt in the parent directory is newer, it overwrites subdir_copy/fileA.txt. If the source were older, no copy would occur.

4.7 -p, —preserve=mode,ownership,timestamps: Preserve attributes

• Description: Preserves the source file’s permissions, ownership, and timestamps.
• Example:

  chmod 600 fileA.txt
  cp -p fileA.txt fileA_preserved.txt
  ls -l fileA.txt fileA_preserved.txt

  Output:

  -rw------- 1 user user 16 May  4 18:54 fileA.txt
  -rw------- 1 user user 16 May  4 18:54 fileA_preserved.txt

  Explanation: fileA_preserved.txt is created with the same permissions (600), ownership, and timestamps as fileA.txt.

4.8 -a, —archive: Archive mode (recursive + preserve all)

• Description: Combines recursive copying with preservation of all attributes, including permissions, timestamps, and symbolic links, ideal for backups.
• Example:

  cp -a subdir subdir_archived
  ls -lR subdir_archived

  Output:

  subdir_archived:
  total 12
  -rw-r--r-- 1 user user  0 May  4 18:54 empty_file
  -rw-r--r-- 1 user user 16 May  4 18:54 fileA.txt
  -rw-r--r-- 1 user user 16 May  4 18:54 fileB.log
  -rw-r--r-- 1 user user 13 May  4 18:54 sub_file.txt

  Explanation: subdir_archived is an exact replica of subdir, including all files and their attributes.

4.9 -L, —dereference: Follow symbolic links in SOURCE

• Description: Copies the file a symbolic link points to, not the link itself.
• Example:

  mkdir copyL
  cp -L link_to_fileB copyL/
  ls -l copyL/

  Output:

  total 4
  -rw-r--r-- 1 user user 16 May  4 18:54 link_to_fileB

  Explanation: copyL/link_to_fileB is a regular file containing the content of fileB.log, not a symbolic link.

4.10 -P, —no-dereference: Do not follow symbolic links in SOURCE

• Description: Copies the symbolic link itself (default behavior).
• Example:

  mkdir copyP
  cp -P link_to_fileB copyP/
  ls -l copyP/

  Output:

  total 0
  lrwxrwxrwx 1 user user 9 May  4 18:54 link_to_fileB -> fileB.log

  Explanation: copyP/link_to_fileB is a symbolic link pointing to fileB.log, preserving the link structure.

4.11 -d: Preserve links

• Description: Equivalent to --no-dereference --preserve=links, ensures symbolic links are copied as links during recursive copying.
• Example:

  cp -d link_to_fileB copyP/link_to_fileB_d
  ls -l copyP/

  Output:

  total 0
  lrwxrwxrwx 1 user user 9 May  4 18:54 link_to_fileB -> fileB.log
  lrwxrwxrwx 1 user user 9 May  4 18:54 link_to_fileB_d -> fileB.log

  Explanation: copyP/link_to_fileB_d is a symbolic link, identical to link_to_fileB.

4.12 -l, —link: Create hard links instead of copying

• Description: Creates a hard link to the source file, sharing the same data on disk, saving space but limited to the same filesystem.
• Example:

  cp -l fileA.txt fileA_hardlink.txt
  ls -i fileA.txt fileA_hardlink.txt

  Output:

  123456 fileA.txt
  123456 fileA_hardlink.txt

  Explanation: fileA_hardlink.txt is a hard link with the same inode as fileA.txt, pointing to the same data.

4.13 -s, —symbolic-link: Create symbolic links instead of copying

• Description: Creates a symbolic link to the source file at the destination.
• Example:

  cp -s fileA.txt fileA_symlink.txt
  ls -l fileA_symlink.txt

  Output:

  lrwxrwxrwx 1 user user 9 May  4 18:54 fileA_symlink.txt -> fileA.txt

  Explanation: fileA_symlink.txt is a symbolic link pointing to fileA.txt.

4.14 —parents: Use full source path under destination directory

• Description: Replicates the source file’s directory structure within the destination directory.
• Example:

  mkdir -p source_dir/level1
  touch source_dir/level1/data.txt
  mkdir destination_dir
  cp --parents source_dir/level1/data.txt destination_dir/
  ls -R destination_dir/

  Output:

  destination_dir/:
  source_dir
  
  destination_dir/source_dir:
  level1
  
  destination_dir/source_dir/level1:
  data.txt

  Explanation: The directory structure source_dir/level1/data.txt is recreated under destination_dir/.

4.15 -b, —backup: Create backups of overwritten files

• Description: Creates backups of destination files before overwriting, typically with a ~ suffix.
• Example:

  echo "Original content." > fileA_copy.txt
  cp -b fileA.txt fileA_copy.txt
  ls

  Output:

  empty_file  fileA_copy.txt  fileA_copy.txt~  fileA.txt  fileB.log  file with spaces.txt  link_to_fileB  subdir

  Explanation: fileA_copy.txt is overwritten with fileA.txt’s content, and a backup fileA_copy.txt~ is created with the original content.

4.16 —sparse=WHEN: Optimize copying sparse files

• Description: Optimizes copying of sparse files (files with large zero-filled regions) to save disk space. Options include always, auto, or never.
• Example:

  # Create a sparse file
  dd if=/dev/zero of=sparse_file bs=1M count=0 seek=100
  cp --sparse=always sparse_file sparse_copy
  ls -ls sparse_file sparse_copy

  Output:

  0 -rw-r--r-- 1 user user 104857600 May  4 18:54 sparse_copy
  0 -rw-r--r-- 1 user user 104857600 May  4 18:54 sparse_file

  Explanation: sparse_copy is a sparse file, using minimal disk space despite its large apparent size, matching sparse_file.

4.17 —reflink=WHEN: Use copy-on-write

• Description: Uses copy-on-write on supported filesystems (e.g., Btrfs, XFS) for faster, space-efficient copies. Options include always, auto, or never.
• Example (on a Btrfs filesystem):

  cp --reflink=always fileA.txt fileA_reflink.txt
  ls

  Output:

  empty_file  fileA_copy.txt  fileA_reflink.txt  fileA.txt  fileB.log  file with spaces.txt  link_to_fileB  subdir

  Explanation: fileA_reflink.txt is a reflink to fileA.txt, sharing data blocks until modified, saving space.

4.18 —preserve=ATTR_LIST: Preserve specific attributes

• Description: Preserves specific attributes (e.g., mode, ownership, timestamps, context, links, xattr, all). More granular than -p.
• Example:

  chmod 600 fileA.txt
  cp --preserve=mode,ownership fileA.txt fileA_preserved_attrs.txt
  ls -l fileA.txt fileA_preserved_attrs.txt

  Output:

  -rw------- 1 user user 16 May  4 18:54 fileA.txt
  -rw------- 1 user user 16 May  4 18:54 fileA_preserved_attrs.txt

  Explanation: fileA_preserved_attrs.txt retains fileA.txt’s mode and ownership, but not necessarily timestamps unless specified.

4.19 -f, —force: Force removal of destination if it can’t be opened

• Description: Removes the destination file if it cannot be opened for writing, then retries the copy. Use cautiously to avoid data loss.
• Example:

  # Create a read-only file
  echo "Protected content." > protected.txt
  chmod 400 protected.txt
  cp -f fileA.txt protected.txt
  ls -l protected.txt

  Output:

  -r-------- 1 user user 16 May  4 18:54 protected.txt

  Explanation: The -f option removes protected.txt (if permissions allow) and copies fileA.txt to it. Without -f, the copy might fail due to permissions.

4.20 -T, —no-target-directory: Treat destination as a file

• Description: Treats the destination as a file, not a directory, even if it exists as a directory, which can lead to errors if misused.
• Example:

  cp -T fileA.txt subdir

  Output:

  cp: cannot overwrite directory 'subdir' with non-directory

  Explanation: The command fails because subdir is a directory, and -T expects a file. Use with caution to avoid errors.

4.21 -Z, —context: Set SELinux security context

• Description: Sets the SELinux security context of the destination file, useful in SELinux-enabled systems.
• Example (on an SELinux-enabled system):

  cp -Z fileA.txt fileA_selinux.txt
  ls -Z fileA_selinux.txt

  Output (example SELinux context):

  -rw-r--r--. 1 user user unconfined_u:object_r:user_home_t:s0 16 May  4 18:54 fileA_selinux.txt

  Explanation: fileA_selinux.txt is created with the default SELinux context for the destination, ensuring compatibility with SELinux policies.

5. Combining Options

Combining options allows for tailored copying operations. Below are examples demonstrating common combinations, with input commands, outputs, and explanations.

Example 5.1: Recursive Copy with Verbose Output

• Command: Copy subdir recursively, showing each file copied.

  cp -rv subdir subdir_verbose_copy

  Output:

  'subdir/empty_file' -> 'subdir_verbose_copy/empty_file'
  'subdir/fileA.txt' -> 'subdir_verbose_copy/fileA.txt'
  'subdir/fileB.log' -> 'subdir_verbose_copy/fileB.log'
  'subdir/sub_file.txt' -> 'subdir_verbose_copy/sub_file.txt'

  Explanation: The -r option ensures recursive copying, and -v displays each file as it’s copied. A new directory subdir_verbose_copy is created with all files from subdir.

Example 5.2: Preserve Attributes and Prompt Before Overwriting

• Command: Copy fileA.txt to subdir_copy/, preserving attributes and prompting for overwrites.

  cp -pin fileA.txt subdir_copy/

  Output (if fileA.txt exists in subdir_copy/):

  cp: overwrite 'subdir_copy/fileA.txt'? y

  Explanation: The -p option preserves permissions, ownership, and timestamps, -i prompts before overwriting, and -n ensures no overwrite if the user declines. If y is entered, subdir_copy/fileA.txt is updated with preserved attributes.

Example 5.3: Copy Only Newer Files with Archive Mode

• Command: Copy subdir to backup/, only updating newer files and preserving all attributes.

  mkdir backup
  cp -au subdir backup/
  ls backup/

  Output:

  subdir

  Explanation: The -a option preserves all attributes and copies recursively, while -u ensures only newer files are copied. The backup/ directory contains an updated subdir with preserved attributes.

6. Handling Special Cases

Special cases require specific handling to ensure successful copying. Below are examples with commands, outputs, and explanations.

6.1 Filenames with Spaces

• Description: Filenames containing spaces must be quoted or escaped to avoid errors.
• Example:

  cp "file with spaces.txt" subdir/
  ls subdir/

  Output:

  empty_file  fileA.txt  file with spaces.txt  fileB.log  sub_file.txt

  Explanation: Quoting "file with spaces.txt" ensures the filename is treated as a single argument. The file is copied to subdir/ without issues.

6.2 Access Control Lists (ACLs)

• Description: Files with ACLs (indicated by a + in ls -l, e.g., -rw-rw-r--+) require special handling to preserve extended permissions.
• Example:

  # Set an ACL on fileA.txt
  setfacl -m u:guest:r fileA.txt
  ls -l fileA.txt
  cp -a fileA.txt fileA_acl_copy.txt
  getfacl fileA_acl_copy.txt

  Output:

  -rw-r--r--+ 1 user user 16 May  4 18:54 fileA.txt
  # file: fileA_acl_copy.txt
  # owner: user
  # group: user
  user::rw-
  user:guest:r--
  group::r--
  mask::r--
  other::r--

  Explanation: The -a option preserves ACLs, so fileA_acl_copy.txt retains the same ACLs as fileA.txt, as confirmed by getfacl.

6.3 Copying to a Read-Only Filesystem

• Description: Copying to a read-only filesystem will fail unless handled appropriately (e.g., using sudo or changing permissions).
• Example (assuming /mnt/readonly is read-only):

  cp fileA.txt /mnt/readonly/

  Output:

  cp: cannot create regular file '/mnt/readonly/fileA.txt': Read-only file system

  Explanation: The command fails due to the read-only filesystem. To resolve, mount the filesystem as writable or use a different destination.

7. Advanced/Other Options (Brief Mention)

• SELinux/SMACK Context (-Z, —context): Sets security contexts for the destination file, useful in SELinux environments.

8. Frequently Asked Questions (FAQ)

8.1 How do I copy an entire directory?

To copy an entire directory, including all its contents, use the -r (recursive) option to copy subdirectories and files, or the -a (archive) option to preserve attributes like permissions, timestamps, and symbolic links. The -a option is ideal for backups as it ensures an exact replica.

• Example:

  cp -a source_dir destination_dir

• Explanation: This command copies source_dir and all its contents to destination_dir, preserving all file attributes.

8.2 How do I preserve permissions and timestamps when copying files?

Use the -p option to preserve mode, ownership, and timestamps for individual files. For directories, use -a to preserve all attributes, including symbolic links and ACLs. Root privileges may be needed to preserve ownership.

• Example:

  cp -p file.txt backup/
  cp -a source_dir backup_dir

• Explanation: The first command copies file.txt to backup/, keeping its permissions and timestamps. The second command copies source_dir to backup_dir, preserving all attributes.

8.3 How can I avoid overwriting existing files?

Use -i to prompt before overwriting, -n to skip overwriting without prompting, or -u to copy only when the source is newer than the destination or the destination is missing.

• Example:

  cp -i source_file destination
  cp -n source_file destination
  cp -u source_file destination

• Explanation: -i asks for confirmation before overwriting, -n prevents overwriting, and -u copies only if source_file is newer.

8.4 What’s the difference between cp -r and cp -a?

The -r option copies directories recursively, while -a (archive mode) includes -r and preserves all attributes, such as permissions, timestamps, and symbolic links. Use -a for exact duplicates, especially for backups.

• Example:

  cp -r source_dir dest_dir
  cp -a source_dir dest_dir

• Explanation: Both commands copy source_dir to dest_dir, but -a ensures all attributes are preserved.

8.5 How do I copy hidden files?

Hidden files (starting with a dot) are included by default when copying directories with -r or -a. For wildcard patterns, enable dotfile globbing with shopt -s dotglob in Bash.

• Example:

  cp -r source_dir dest_dir
  shopt -s dotglob
  cp source_dir/* dest_dir/
  shopt -u dotglob

• Explanation: The first command copies all files, including hidden ones, from source_dir to dest_dir. The second enables dotfile globbing to include hidden files with wildcards.

8.6 What happens if SOURCE and DEST are the same file?

If the source and destination are the same file, cp detects this and reports an error to prevent data loss.

• Example:

  cp file.txt file.txt

• Output:

  cp: 'file.txt' and 'file.txt' are the same file

• Explanation: The command fails to avoid overwriting the file with itself.

8.7 How do I copy only newer files?

Use the -u (update) option to copy files only if the source is newer than the destination or if the destination does not exist.

• Example:

  cp -u source_file dest_file
  cp -u source_dir/* dest_dir/

• Explanation: The first command copies source_file to dest_file only if it’s newer. The second copies newer files from source_dir to dest_dir.

8.8 How do I handle symbolic links with cp?

By default, cp copies symbolic links as links (-P). Use -L to copy the target file instead. For directories, -a preserves links during recursive copying.

• Example:

  cp -P link_to_file dest/
  cp -L link_to_file dest/
  cp -a source_dir dest_dir

• Explanation: -P copies the link, -L copies the target, and -a preserves links in directories.

8.9 Can I copy files across different filesystems?

Yes, cp can copy files across filesystems, but some attributes like hard links or extended attributes may not be preserved. For large transfers, rsync may be more efficient.

• Example:

  cp /source/file.txt /mnt/other_fs/

• Explanation: Copies file.txt to a different filesystem at /mnt/other_fs/.

8.10 Why does cp file1 file2 file3 dest fail if dest is not a directory?

When multiple source files are specified, dest must be a directory. If dest is a file, cp fails because it cannot copy multiple files into a single file.

• Example:

  cp file1.txt file2.txt file3.txt dest_file

• Output:

  cp: target 'dest_file' is not a directory

• Explanation: The command fails as dest_file is not a directory.

8.11 Does cp copy hidden files in directories?

Yes, hidden files are copied by default when using -r or -a for directories.

• Example:

  cp -r source_dir dest_dir

• Explanation: All files, including hidden ones, are copied from source_dir to dest_dir.

8.12 Why does cp hang or take a long time?

cp may hang due to slow devices, large files, permission issues, or full filesystems. Check disk space, permissions, and device performance.

• Example:

  cp large_file.txt dest/

• Explanation: Copying large files to slow devices can cause delays.

8.13 How do I prompt before overwriting during recursive copying?

Use -i with -r to prompt before overwriting files during recursive copying.

• Example:

  cp -ri source_dir dest_dir

• Explanation: Prompts for confirmation before overwriting any file in dest_dir.

8.14 How do I preserve symbolic links in directories?

Use -a to preserve symbolic links and other attributes during directory copying.

• Example:

  cp -a source_dir dest_dir

• Explanation: Copies source_dir to dest_dir, preserving symbolic links.

8.15 What’s the difference between cp and rsync?

cp is a simple local copying tool, while rsync supports advanced features like delta transfers, remote copying, and synchronization, making it better for backups.

• Example:

  rsync -av source_dir dest_dir

• Explanation: Synchronizes source_dir with dest_dir, transferring only differences.

8.16 How do I copy a directory structure without files?

cp does not directly support this. Use find to create the directory structure without files.

• Example:

  find source_dir -type d -exec mkdir -p dest_dir/{} \;

• Explanation: Creates all directories from source_dir in dest_dir without copying files.

8.17 Why does cp fail with “No space left on device”?

This error occurs when the filesystem is full or inodes are exhausted. Check disk space and inodes with df.

• Example:

  df -h
  df -i

• Explanation: df -h checks disk space, and df -i checks inode usage. Clean up files or increase inodes if needed.

9. Conclusion

The cp command is a powerful tool for file and directory management in Linux. Its basic functionality is simple, but options like -r, -a, -p, -i, -u, and those for symbolic links (-L, -P, -d) provide fine-grained control. By understanding these options and considering permissions and overwrite risks, users can perform efficient and safe copying operations. For detailed information, consult the man page for cp .

10. cp Command: Reference Table of Key Options

(Copy files and directories)