How to Exclude Files & Directories from cPanel Backups (cpbackup-exclude.conf Guide)

Automated cPanel backups are your primary safety net against catastrophic hardware failure, plugin update crashes, and developer errors. However, on active websites, staging environments, and high-traffic e-commerce portals, full account backups frequently become an operational nightmare.

You might notice your nightly backups taking five hours to compress, triggering server-wide CPU load spikes, or failing entirely with errors like gzip: stdout: No space left on device.

In almost every case, the root cause is identical: cPanel is diligently compressing dozens of gigabytes of useless clutter—including bloated error_log files, expired caching directories, staging database dumps, and node_modules folders.

By configuring cPanel’s native cpbackup-exclude.conf file, you can instruct backup scripts to ignore these non-essential directories, slashing backup duration and reclaiming vital server storage.

---

1. How cPanel Backup Exclusion Works

cPanel’s internal backup utilities (pkgacct, WHM Automated Backups, and user-initiated cPanel Full Backups) check for an exclusion configuration file before building the compressed tarball:

┌────────────────────────────────────────────────────────────────────────┐
│                   CPANEL BACKUP EXCLUSION ARCHITECTURE                 │
├────────────────────────────────────────────────────────────────────────┤
│  Backup Process Initiated (pkgacct / cron / WHM Backup Manager)        │
│                                │                                       │
│  Script Inspects: /home/username/cpbackup-exclude.conf                 │
│                   AND /etc/cpbackup-exclude.conf (Server-Wide)         │
│                                │                                       │
│  [Does Path Match An Exclusion Pattern?]                               │
│         │                               │                              │
│       YES                             NO                               │
│         ▼                               ▼                              │
│   SKIPPED FROM TARBALL            COMPRESSED & INCLUDED IN BACKUP      │
│   (Saves CPU, IOPS & Storage)     (Preserves Core Code & Databases)    │
└────────────────────────────────────────────────────────────────────────┘

cPanel supports exclusions at two operational levels:

1. User-Level Exclusion: Placed at /home/$USER/cpbackup-exclude.conf. Affects only that specific cPanel user account.
2. Server-Wide Exclusion (Root Sysadmins): Placed at /etc/cpbackup-exclude.conf. Enforces rules across every cPanel account hosted on the server.

---

2. Step-by-Step: Creating a User-Level cpbackup-exclude.conf

If you are a website owner or cPanel user without root SSH privileges, you can configure your exclusions directly via the cPanel File Manager or Terminal.

Step 1: Access Your Home Directory

1. Log into your cPanel dashboard.
2. Open File Manager.
3. Ensure you are in your account root directory (/home/yourusername/), which is one level above public_html.
4. Click Settings (top right) and ensure “Show Hidden Files (dotfiles)” is checked.

Step 2: Create or Edit cpbackup-exclude.conf

Check if cpbackup-exclude.conf already exists. If not, click + File at the top left and create a file named exactly:

cpbackup-exclude.conf

Step 3: Populate with Exclude Rules

Paths in cpbackup-exclude.conf must be relative to the user’s home directory (do NOT include /home/username/ in the path).

Here is a battle-tested template for modern WordPress, Laravel, and e-commerce websites:

# Exclude PHP error logs across the entire account
*/error_log
public_html/*/error_log
public_html/error_log

# Exclude WordPress caching directories (LSCache, WP Rocket, Super Cache)
public_html/wp-content/cache/*
public_html/wp-content/litespeed/*

# Exclude UpdraftPlus and third-party local backup dumps inside wp-content
public_html/wp-content/updraft/*
public_html/wp-content/ai1wm-backups/*

# Exclude Node and Composer package dependencies
*/node_modules/*
*/vendor/*

# Exclude Git repositories and staging branches
public_html/.git/*
staging.yourdomain.com/*

# Exclude temporary zip files, tarballs, and SQL dumps left by developers
*.zip
*.tar.gz
*.sql
*.tar

Click Save Changes. The next time an automated backup or manual full backup runs, these heavy directories will be bypassed.

---

3. Server-Wide Exclusions (For VPS & Dedicated Server Sysadmins)

If you manage a Cloud VPS or bare-metal dedicated server hosting dozens of client accounts, you should enforce server-wide hygiene to prevent any single tenant from exhausting backup disk volumes.

Connect to your server via SSH as root and edit /etc/cpbackup-exclude.conf:

nano /etc/cpbackup-exclude.conf

Add universal patterns:

*/error_log
*/wp-content/cache/*
*/node_modules/*
*.tar.gz
*.zip
*.sql
.trash/*

Save and exit (Ctrl + O, then Ctrl + X).

Testing Your Exclusions via Terminal

You can test whether your exclusion file works without waiting for the nightly cron job by running the cPanel account packaging script manually:

/scripts/pkgacct username /backup/test/

Inspect the output terminal log. You will observe lines verifying that excluded paths are skipped during the tar packaging phase.

---

4. The Benefits: Backup Duration & I/O Reduction

Implementing standard backup exclusions yields dramatic performance improvements across your server:

┌────────────────────────┬────────────────────────┬────────────────────────┐
│ METRIC                 │ WITHOUT EXCLUSIONS     │ WITH EXCLUSION RULES   │
├────────────────────────┼────────────────────────┼────────────────────────┤
│ Backup Archive Size    │ 42.8 GB (Full Clutter) │ 6.4 GB (Clean Code/DB) │
│ Compression Duration   │ 48 Minutes             │ 6 Minutes (-87% Faster)│
│ Storage IOPS Consumed  │ Heavy Disks Throttling │ Minimal Background I/O │
│ Offsite S3 Transfer    │ Expensive Bandwidth    │ Instant Sync           │
└────────────────────────┴────────────────────────┴────────────────────────┘

1. Faster Restoration Times: In a disaster recovery event, extracting a 6 GB archive takes seconds, whereas extracting a 40 GB archive crammed with millions of tiny cache files can take hours.
2. Lower Offsite Storage Costs: If you push daily backups to Amazon S3, Google Cloud Storage, or Wasabi, reducing backup file sizes saves significant monthly storage and bandwidth egress fees.
3. Zero Backup Failures: Eliminates sudden disk-full crashes during nightly backup generation.

---

5. Upgrade to Infrastructure with Dedicated Backup Drives

While software-level backup exclusions keep your storage tidy, running heavy backup routines on the same physical drive as your live production database causes noticeable I/O latency for visitors.

High-performance Dedicated Servers allow you to install a dedicated secondary storage drive (or an attached NFS/NAS storage network) specifically dedicated to automated backups, isolating backup I/O from your primary operating system.

For enterprises requiring high performance and strict domestic data protection, our Dedicated Servers in Pakistan provide unshared hardware resources, high-throughput network backbones, and 24/7 dedicated system engineering support.