VMware ESXi and vSphere Cluster Management

Using the cpio Program to Create, Extract, and Copy Archives in Linux

Learn how to use Linux cpio copy-out, copy-in, and copy-pass modes to create archives, extract files, copy directory trees, and preserve metadata.

What is cpio?

cpio is a Unix and Linux command-line utility for archiving, extracting, and copying files. Its name comes from “copy in/out,” describing its original two-way archive workflow.

An archive is a single file containing one or more files or directories, often together with metadata such as ownership and modification times. cpio creates and reads archive containers, but it does not compress them by itself.

cpio commonly receives a list of pathnames through standard input. Standard input is the input stream a command reads from the terminal, another command, or a file. The find command is often used to generate this pathname list.

Compression is a separate operation. For example, you can create an archive with cpio and then compress it with gzip, producing a file such as archive.cpio.gz.

The three cpio operating modes

cpio has three primary operating modes. The first mode option tells cpio what operation to perform.

Mode	Option	Input	Output or result	Typical use
Copy-out	`-o`, `--create`	Pathnames from standard input	Archive data written to standard output	Create an archive
Copy-in	`-i`, `--extract`	Archive data from standard input	Files extracted into the current directory or another selected location	Extract an archive
Copy-pass	`-p`, `--pass-through`	Pathnames from standard input	Files copied to a destination directory	Copy a directory tree without creating an archive

Common options

Option	Long option	Purpose
`-o`	`--create`	Select copy-out mode and create an archive
`-i`	`--extract`	Select copy-in mode and extract an archive
`-p`	`--pass-through`	Select copy-pass mode and copy files to a destination
`-v`	Usually no separate long option is needed	Enable verbose output, reporting processed pathnames
`-d`	`--make-directories`	Create required destination directories during copying or extraction

Options are often combined, as in -ov for copy-out with verbose output or -pvd for copy-pass with verbose output and directory creation.

Shell data flow in cpio commands

Understanding shell data flow makes cpio commands easier to read.

Operator	Meaning	Example role
Pipe (`\|`)	Passes one command’s standard output to another command’s standard input	Sends pathnames from `find` to cpio
Output redirection (`>`)	Writes a command’s standard output to a file	Saves copy-out archive data as `archive.cpio`
Input redirection (`<`)	Reads a file as a command’s standard input	Sends an existing archive file to copy-in mode

In a creation command, the pipe supplies a pathname list to cpio, while > saves the archive stream. In an extraction command, < supplies archive data to cpio. These are different kinds of input: a pathname list for copy-out and copy-pass, versus archive bytes for copy-in.

Copy-out mode: creating archives

Copy-out mode reads pathnames from standard input and writes an archive to standard output. Use -o or --create.

Archive entries in the current directory

The following command uses find to produce a recursive list starting at the current directory:

find . -print | cpio -ov > archive.cpio

find . -print emits the current directory and its files and subdirectories.
The pipe (|) sends those pathnames to cpio.
-o selects copy-out mode.
-v prints each processed pathname.
> archive.cpio saves the archive stream in a file.

The paths stored by this example are relative paths beginning with ./. Using find is preferable to using ls because find can traverse directories recursively and generates pathnames rather than display-oriented listings.

Archive a specified directory tree

To archive /home/bob/example_dir and everything below it, use:

find /home/bob/example_dir -print | cpio -ov > example_dir.cpio

Here, find supplies pathnames from the named directory tree. The stored pathnames reflect the paths emitted by find. Because these are absolute pathnames, extracting the archive can recreate the corresponding directory layout and may require suitable permissions.

For more predictable, portable archive paths, change to the intended parent directory and search with a relative path:

cd /home/bob
find example_dir -print | cpio -ov > example_dir.cpio

This stores names such as example_dir/file.txt instead of names beginning with /home/bob/.

Copy-in mode: extracting archives

Copy-in mode reads archive data from standard input and extracts its members. Use -i or --extract.

Extract the archive created in copy-out mode

Run the extraction from the directory where you want the archive contents to appear:

cpio -iv < archive.cpio

-i selects copy-in mode.
-v displays the names being extracted.
< archive.cpio supplies the archive file as cpio’s standard input.

Unless paths or other options change the behavior, extraction occurs relative to the current working directory. Before extracting an archive, choose an appropriate destination directory and verify that you have permission to create its files.

Inspecting and selecting archive members

Checking an archive’s contents before extraction helps reveal its stored pathnames:

cpio -itv < archive.cpio

The -t option lists archive contents without extracting them. Copy-in mode can also be combined with name patterns to extract only selected members; consult your system’s cpio manual for pattern matching details.

Copy-pass mode: copying directory contents

Copy-pass mode reads a pathname list and copies the listed files into a destination directory. Use -p or --pass-through. Unlike copy-out mode, it does not produce an archive file.

Copy a directory tree to another location

First make sure the destination exists and is writable:

mkdir -p /home/bob/new_directory

Then copy the source tree:

find /home/bob/example_dir -print | cpio -pvd /home/bob/new_directory

find generates the source pathname list.
-p selects copy-pass mode.
-v reports copied pathnames.
-d creates required destination directories.
/home/bob/new_directory is the destination argument.

The source files remain in place. This is a copy operation, not a move. cpio’s pass-through workflow can preserve useful metadata, including modification times and ownership, subject to the user’s permissions and the operating system’s ability to restore those attributes. Restoring ownership commonly requires appropriate privileges.

Destination directories should exist before the operation, and -d should be used when the source contains a directory hierarchy that must be recreated.

Compression is a separate step

cpio creates an archive container; gzip compresses data. They can be used in sequence.

Compress a completed archive

gzip archive.cpio

This normally replaces archive.cpio with archive.cpio.gz. The resulting file is a gzip-compressed cpio archive, not an archive created by gzip alone.

Decompress before extraction

gunzip archive.cpio.gz && cpio -iv < archive.cpio

gunzip restores the uncompressed cpio stream. The && operator runs the extraction only if decompression succeeds.

Troubleshooting cpio commands

Unexpected paths during extraction

If extraction creates an unwanted directory layout, inspect the names stored in the archive:

cpio -itv < archive.cpio

The likely cause is that find emitted absolute paths or included an undesired leading directory. Run find from the intended parent directory and use relative paths when creating the archive.

Copy-pass cannot create destination paths

The destination directory tree may not exist, or the current user may not be allowed to write there. Create the destination with mkdir -p, use -d, and verify its permissions.

Permission or ownership errors

Permission errors can mean that the user cannot read source files, write the destination, or restore ownership. Check file and directory permissions. Use elevated privileges only when necessary and only when you understand which ownership and permission changes will occur.

A gzip archive fails during extraction

A file ending in .gz is compressed, so it cannot always be supplied directly where cpio expects an uncompressed archive stream. Decompress it with gunzip first, then run cpio in copy-in mode.

The archive is empty or missing files

The pathname-producing command may have searched the wrong directory or matched fewer files than expected. Inspect its output before piping it to cpio:

find . -print

Confirm the current working directory, the search path, and any selection conditions.

Exam-relevant summary

Copy-out: find ... | cpio -o creates an archive from a pathname list.
Copy-in: cpio -i < archive.cpio extracts archive data supplied through standard input.
Copy-pass: find ... | cpio -p destination copies selected files without making an archive.
Verbose output: add -v to report processed pathnames.
Directory creation: add -d when destination directories need to be created.
Compression: cpio and gzip perform separate jobs; use gzip after creating the archive and gunzip before extraction.
Path safety: the names emitted by find determine the paths stored or copied, so inspect them before running a large operation.

For related archive work, see the cpio program reference.