cpx

---

Why cpx?

cpx is a modern replacement for the traditional cp command, built with Rust for maximum performance and safety on Linux systems.

Features

• 🚀 Fast parallel copying (upto 5x faster than cp benchmarks)
• 📊 Beautiful progress bars (customizable)
• ⏸️ Resume interrupted transfers
• 🛑 Graceful Ctrl+C handling with resume hints
• 🎯 Exclude patterns (gitignore-style)
• ⚙️ Flexible configuration

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/11happy/cpx/main/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/11happy/cpx/main/install.sh | bash

From Crates.io

cargo install cpx

Arch Linux (AUR)

Added by community

yay -S cpx-copy

Nix / NixOS

Added by community

nix-shell -p cpx

From Source

cargo install --git https://github.com/11happy/cpx
cpx --version

Pre-built Binaries

Download from Releases

Quick Start

Basic Usage

# Copy a file
cpx source.txt dest.txt

# Copy directory recursively
cpx -r source_dir/ dest_dir/

# exclude build artifacts
cpx -r -e "node_modules" -e ".git" -e "target" my-project/ /backup/

# Resume interrupted transfer
cpx -r --resume large_dataset/ /backup/

# Copy with full attribute preservation
cpx -r -p=all photos/ /backup/photos/

See examples.md for detailed workflows and real-world scenarios.

Key Options

cpx [OPTIONS] <SOURCE>... <DESTINATION>

Arguments:
  <SOURCE>...       Source file(s) or directory(ies)
  <DESTINATION>     Destination file or directory

Input/Output Options:
  -t, --target-directory <DIRECTORY>
                           Copy all SOURCE arguments into DIRECTORY
  -e, --exclude <PATTERN>  Exclude files matching pattern (supports globs, comma-separated)

Copy Behavior:
  -r, --recursive          Copy directories recursively
  -j <N>                   Number of parallel operations [default: 4]
      --resume             Resume interrupted transfers (checksum verified)
  -f, --force              Remove and retry if destination cannot be opened
  -i, --interactive        Prompt before overwrite
      --parents            Use full source file name under DIRECTORY
      --attributes-only    Copy only attributes, not file data
      --remove-destination Remove destination file before copying

Link and Symlink Options:
  -s, --symbolic-link [MODE]
                           Create symlinks instead of copying [auto|absolute|relative]
  -l, --link               Create hard links instead of copying
  -P, --no-dereference     Never follow symbolic links in SOURCE
  -L, --dereference        Always follow symbolic links in SOURCE
  -H, --dereference-command-line
                           Follow symbolic links only on command line

Preservation:
  -p, --preserve [ATTRS]   Preserve attributes [default|all|mode,timestamps,ownership,...]
                           Available: mode, ownership, timestamps, links, context, xattr

Backup and Reflink:
  -b, --backup [MODE]      Backup existing files [none|simple|numbered|existing]
      --reflink [WHEN]     CoW copy if supported [auto|always|never]

Configuration:
      --config <PATH>      Use custom config file
      --no-config          Ignore all config files

Other:
  -h, --help               Print help information
  -V, --version            Print version information

For complete usage examples, see examples.md

For complete option reference, run cpx --help

Configuration

Set defaults with configuration files:

# Create config with defaults
cpx config init

# View active configuration
cpx config show

# See config file location
cpx config path

Config locations (in priority order):

1. ./cpxconfig.toml (project-level)
2. ~/.config/cpx/cpxconfig.toml (user-level)
3. /etc/cpx/cpxconfig.toml (system-level, Unix only)

Example config (~/.config/cpx/cpxconfig.toml):

[exclude]
patterns = ["*.tmp", "*.log", "node_modules", ".git"]

[copy]
parallel = 8
recursive = false

[preserve]
mode = "default"

[progress]
style = "detailed"

[reflink]
mode = "auto"

See configuration.md for all options and use cases.

Performance

cpx is built for speed. Quick comparison:

Task	cp	cpx -j16	speedup
VsCode (~15k files)	1084ms	263ms	4.12x
rust (~65k files)	4.553s	1.091s	4.17x

See benchmarks.md for detailed methodology and more comparisons.

Documentation

• Configuration Guide - Complete config reference
• Benchmarks - Performance analysis and comparisons
• Contributing - How to contribute

Platform Support

Platform	Status	Notes
Linux	✅ Supported	Fast copy supported for (kernel 4.5+)
macOS	🔄 Planned	To be released
Windows	🔄 Planned	To be released

Quick Start for Developers

git clone https://github.com/11happy/cpx.git
cd cpx

# Run tests
cargo test

# Run clippy
cargo clippy

# Try it out
cargo run -- -r test_data/ test_dest/

Tests

Some tests are already ported from the GNU coreutils cp test suite, still porting more GNU ported tests.

Found wrong behavior? File an issue, PRs for more tests are always welcome!

License

• MIT LICENSE

Acknowledgments

Inspired by ripgrep, fd, and the modern Rust CLI ecosystem.

Built with: clap, indicatif, rayon, jwalk, and more.

---