Guides

AWS S3 sync Command with Examples: Upload, Download, --delete and --exclude

By Ravindra Bagale, AWS & DevOps trainer · LinkedIn · Published: 16 October 2026 · Last updated: 17 October 2026

aws s3 sync copies only the new or changed files between a local folder and an S3 bucket (or between two buckets). For example, aws s3 sync ./site s3://my-bucket uploads your website and skips files that are already the same. Add --dryrun to preview, --exclude to skip files, and --delete to remove files from the destination that no longer exist in the source. Use --delete only after a dry run, with S3 Versioning turned on.

aws s3 sync ./site s3://rb-site-2026 --dryrun                  # preview
aws s3 sync ./site s3://rb-site-2026                           # upload changes
aws s3 sync s3://rb-site-2026 ./backup                         # download
aws s3 sync ./site s3://rb-site-2026 --delete --exclude ".git/*"   # mirror
aws s3 sync s3://rb-logs-mumbai s3://rb-logs-dr --source-region ap-south-1 --region ap-southeast-1

A live example first

We host a static training site from the bucket rb-site-2026 (ap-south-1). The local build folder is ./dist.

1. First upload, preview:

aws s3 sync ./dist s3://rb-site-2026 --dryrun

(dryrun) upload: dist/index.html to s3://rb-site-2026/index.html
(dryrun) upload: dist/css/site.css to s3://rb-site-2026/css/site.css
(dryrun) upload: dist/img/logo.png to s3://rb-site-2026/img/logo.png

2. Run it for real (remove --dryrun). Three files upload.
3. We edit only index.html and sync again:

aws s3 sync ./dist s3://rb-site-2026

upload: dist/index.html to s3://rb-site-2026/index.html

Only one file moved. That is the power of sync.

4. We deleted img/old-banner.png locally. The bucket still has it. To mirror exactly, preview with --delete:

aws s3 sync ./dist s3://rb-site-2026 --delete --dryrun

(dryrun) delete: s3://rb-site-2026/img/old-banner.png

It deletes only that one file, so we run it without --dryrun. Friends, never skip that preview when --delete is involved.

How does sync decide what to copy?

For every file, sync checks whether it exists on the other side and compares size and last-modified time. If the file is missing or different, it copies it. If it matches, it skips it. It does not compare the content itself. Uploads larger than 8 MB are automatically split into multipart uploads.

How do I use sync step by step?

1. Run aws sts get-caller-identity to make sure you are in the right account.
2. Write the source first and the destination second.
3. Add --dryrun and read every line.
4. Add --exclude / --include filters if needed.
5. Run without --dryrun.
6. For a static site behind CloudFront, invalidate the cache.
7. Check with aws s3 ls s3://bucket --recursive --human-readable --summarize.

Filters: --exclude and --include

Filters are applied in order, and later ones win:

# skip git and node_modules
aws s3 sync . s3://rb-site-2026 --exclude ".git/*" --exclude "node_modules/*"

# only upload HTML files
aws s3 sync . s3://rb-site-2026 --exclude "*" --include "*.html"

Useful options

sync vs cp

Use it from your stack

• CI/CD (GitHub Actions, Jenkins, GitLab): run aws s3 sync dist/ s3://bucket --delete as the deploy step, using an IAM role, not stored keys.
• Python (boto3): boto3 has no sync; use the CLI from a script, or loop with upload_file and compare ETags.
• Node.js: call the CLI, or use the AWS SDK for JavaScript v3 with @aws-sdk/lib-storage for large uploads.
• Backups from Linux: a nightly cron job such as aws s3 sync /var/backups s3://rb-backups/$(hostname)/ --storage-class STANDARD_IA.
• Other clouds: gsutil rsync (Google Cloud) and azcopy sync (Azure) work the same way.

IAM permissions for sync

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::rb-site-2026" },
    { "Effect": "Allow", "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::rb-site-2026/*" }
  ]
}

Leave out s3:DeleteObject if the job should never delete.

Real example: why versioning matters

In 2014, the code-hosting company Code Spaces shut down after an attacker who got into its AWS console deleted most of its data, servers and backups, which all lived in the same account. A wrong --delete is a much smaller accident, but the protection is the same idea: turn on S3 Versioning (and for backups, a separate account and Object Lock), so a deleted or overwritten file can be restored.

Mistakes to avoid

1. Swapping source and destination. aws s3 sync s3://bucket ./site --delete deletes your local work.
2. Using --delete without --dryrun.
3. Syncing secrets. .env files get uploaded too unless you exclude them.

Summary table