---
title: "aws s3 cpの使い方｜再帰コピー・フィルタ・ストリーム転送と終了コードの実装手順"
url: "https://www.issoh.co.jp/tech/details/18008/"
published: 2026-10-01
updated: 2026-10-01
categories: ["AWS"]
publisher: "株式会社一創"
---

# aws s3 cpの使い方｜再帰コピー・フィルタ・ストリーム転送と終了コードの実装手順

`aws s3 cp`は1行で動くぶん、細かな挙動を知らないまま本番のスクリプトに入りがちなコマンドです。コピー先の末尾にスラッシュを付けるかどうかでオブジェクト名が変わる、`--exclude`と`--include`は書く順番で結果が逆になる、一部のファイルだけ失敗しても終了コードが0にならない。この記事では、こうした挙動をAWS CLI 2.37系（2026年10月時点の公式リファレンス表記）の仕様に沿って整理し、実行できるコマンドで示します。バケットの作成や権限設計といったS3全体の手順は[AWS S3の使い方｜CLIでのバケット作成から権限設計・署名付きURLまでの実装手順](https://www.issoh.co.jp/tech/details/17489/)にまとめてあるため、本記事は`cp`の引数と挙動に絞ります。

## まとめ｜aws s3 cpで事故を防ぐために先に押さえる5つの挙動

先に結論を置きます。`aws s3 cp`を自動化に組み込む前に確認しておきたいのは、次の5点です。

- コピー先の末尾が`/`ならコピー元の名前を引き継ぎ、無ければ指定した名前で保存される
- パスにワイルドカードは書けず、絞り込みは`--exclude`と`--include`で行う。後に書いたフィルタが優先される
- コピー元に`-`を指定すると標準入力からアップロードでき、50GBを超えるストリームは`--expected-size`が必要になる
- 新しく作るバケットはACLが無効なので、`--acl public-read`のような指定は400エラーで失敗する
- 終了コード1は転送失敗、2はスキップや構文エラーを示す。0以外をまとめて失敗扱いにすると原因を取り違える

どれも公式ドキュメントに書かれている仕様ですが、入門記事ではほとんど触れられていません。以降で1つずつ手順に落とします。

## aws s3 cpの書式と末尾スラッシュで変わるコピー先の名前の決まり方

前提として、AWS CLI v2が入っていて認証が通っている状態から始めます。導入とSSO認証の設定は[AWS CLIの導入と運用｜v2の設定・SSO認証・v1サポート終了への移行手順](https://www.issoh.co.jp/tech/details/17403/)を参照してください。

### アップロード・ダウンロード・S3間コピーの3方向を1つの書式で書く

[cpのリファレンス](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html)にある通り、書式は`aws s3 cp <コピー元> <コピー先> [オプション]`の1種類だけです。コピー元とコピー先のどちらに`s3://`を書くかで、アップロード、ダウンロード、S3間コピーが切り替わります。

```
# ローカルからS3へアップロード
aws s3 cp ./report.csv s3://example-bucket/reports/report.csv

# S3からローカルへダウンロード
aws s3 cp s3://example-bucket/reports/report.csv ./report.csv

# S3からS3へコピー（ローカルを経由しない）
aws s3 cp s3://example-bucket/reports/report.csv s3://example-archive/2026/report.csv
```

実行すると`upload:`・`download:`・`copy:`のいずれかが1行ずつ表示されます。S3間コピーはサーバー側のCopyObjectで処理されるため、手元の回線を通りません。

### 末尾の/の有無でオブジェクト名が変わるパス引数の規則

[s3コマンド共通のリファレンス](https://docs.aws.amazon.com/cli/latest/reference/s3/)には、コピー先の末尾がスラッシュならディレクトリやプレフィックスとして扱い、コピー元の名前を引き継ぐと書かれています。スラッシュが無ければ、指定した文字列がそのままオブジェクト名になります。

```
# 末尾スラッシュあり：s3://example-bucket/backup/report.csv になる
aws s3 cp ./report.csv s3://example-bucket/backup/

# 末尾スラッシュなし：s3://example-bucket/backup という名前の1オブジェクトになる
aws s3 cp ./report.csv s3://example-bucket/backup
```

後者は「backupフォルダに入れたつもりが、backupという名前のファイルができていた」という取り違えの典型です。S3の`s3://`側は常に`/`、ローカル側はOSの区切り文字を使う点も同じページに明記されています。

## –recursiveと–exclude・–includeによる対象指定と評価順

複数ファイルを扱うときに迷うのがここです。`aws s3 cp ./logs/*.log s3://...`のようなシェルのワイルドカードは、S3側のパスでは解釈されません。

### パスにワイルドカードを書けない場合に対象を絞るフィルタの4記号

ディレクトリやプレフィックス配下をまとめて扱うには`--recursive`を付け、対象を`--exclude`と`--include`で絞ります。[s3コマンド共通のリファレンス](https://docs.aws.amazon.com/cli/latest/reference/s3/)で使える記号は`*`（任意の文字列）、`?`（任意の1文字）、`[sequence]`（列挙した文字のいずれか）、`[!sequence]`（列挙した文字以外）の4つです。

フィルタはコピー元ディレクトリを起点に評価されます。`--exclude ".git/*"`と書けばコピー元直下の`.git`配下が外れます。コピー元が単一ファイルのときは、そのファイルを含むディレクトリが起点です。

### 後に書いたフィルタが勝つ評価順と.logだけを転送するコマンド

同じページに「コマンドの後ろに現れたフィルタが、前に現れたフィルタより優先される」と書かれています。つまり順番を入れ替えると結果が逆になります。

```
# .logだけを転送する（全部除外してから.logを戻す）
aws s3 cp ./logs s3://example-bucket/logs/ \
  --recursive --exclude "*" --include "*.log" --dryrun

# 順番を逆にすると、最後の --exclude "*" が勝って何も転送されない
aws s3 cp ./logs s3://example-bucket/logs/ \
  --recursive --include "*.log" --exclude "*" --dryrun
```

両方に`--dryrun`を付けてあります。実際には転送せず、実行されるはずの操作だけを`(dryrun) upload:`の形で表示するオプションです。フィルタを書いたら、本番の前に必ずこれで対象一覧を目で確かめてください。2本目のコマンドは何も表示されずに終わるので、順番の誤りにその場で気づけます。

### –no-overwriteの上書き回避と–case-conflictの衝突対処

現行のリファレンスには、転送先に同名のファイルがあればスキップする`--no-overwrite`があります。既存のオブジェクトを守りながら、足りないものだけを補充する用途に向きます。

WindowsやmacOSへダウンロードするときは`--case-conflict`も確認してください。S3のキーは大文字と小文字を区別しますが、これらのOSの標準的なファイルシステムは区別しません。`Report.csv`と`report.csv`が両方あると後から落ちたほうが上書きします。既定値は`ignore`（衝突を無視してダウンロード）で、`error`・`warn`・`skip`に変えられます。

## 標準入出力のストリーム転送と50GBを超えるときの–expected-size指定

ここからは入門記事で扱われていない機能です。一時ファイルを作らずにパイプで転送できます。

### コピー元に-を指定してダンプを一時ファイル無しでアップロードする

[cpのリファレンス](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html)では、コピー元に`-`を書くと標準入力から、コピー先に`-`を書くと標準出力へ転送すると定義されています。データベースのダンプを圧縮しながらそのまま保存する例です。

```
# ダンプを圧縮しながらS3へ直接アップロード（ディスクに一時ファイルを残さない）
pg_dump --format=custom appdb | gzip \
  | aws s3 cp - s3://example-backup/db/appdb-20261001.dump.gz

# S3のファイルを標準出力に流して、ダウンロードせずに先頭だけ確認
aws s3 cp s3://example-bucket/logs/app-20261001.log - | head -n 20
```

ディスク容量の小さいバッチサーバーで大きなファイルを扱う場合に効きます。ただし、標準出力へのダウンロードは`--recursive`と組み合わせられません。対象は常に1オブジェクトです。

### パート数1万の上限で50GB超のストリームが途中で失敗する仕組み

ストリームではCLIが全体のサイズを事前に知りません。そのため、既定のチャンクサイズのまま分割していくと、[マルチパートアップロードの上限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html)である1アップロードあたり10,000パートに届いた時点で失敗します。リファレンスは、50GBを超えるストリームでは`--expected-size`にバイト数を渡すよう求めています。

```
# 約60GBのストリームを送る場合はバイト数で予告する
tar -cf - ./dataset | aws s3 cp - s3://example-bucket/dataset.tar \
  --expected-size 64424509440
```

サイズが分かればCLIはパートを大きく取り直せます。パート1つの大きさは5MiB〜5GiB、1オブジェクトの最大サイズは48.8TiBで、これを超える分割はできません。正確なバイト数が出せないときは、少し大きめの見積もりを渡しておけば上限内に収まります。

## ストレージクラス・暗号化・メタデータをcpの引数で指定する実行手順

アップロードと同時に、保管クラス・暗号化・HTTPヘッダを決められます。後から`s3api`で付け直すより手数が減ります。

### –storage-classと–sseをアップロード時に付ける書き方

`--storage-class`に指定できる値は、リファレンス上で`STANDARD`、`REDUCED_REDUNDANCY`、`STANDARD_IA`、`ONEZONE_IA`、`INTELLIGENT_TIERING`、`GLACIER`、`DEEP_ARCHIVE`、`GLACIER_IR`の8種類です。暗号化は`--sse`に`AES256`か`aws:kms`を渡し、カスタマー管理キーを使うときだけ`--sse-kms-key-id`を足します。

```
aws s3 cp ./archive-2025.zip s3://example-archive/2025/ \
  --storage-class GLACIER_IR \
  --sse aws:kms --sse-kms-key-id alias/example-archive-key \
  --metadata project=example,owner=infra

aws s3 cp ./dist/app.js s3://example-assets/static/app.js \
  --content-type "application/javascript" \
  --cache-control "public, max-age=31536000, immutable"
```

アーカイブ系のクラスは最小保存期間と取り出し料金が付くため、少量の短期ファイルを直接入れると割高になります。クラスごとの考え方は[Amazon S3とは？オブジェクトストレージの仕組み・ストレージクラスと料金・採用判断を実装者目線で解説](https://www.issoh.co.jp/tech/details/15433/)に、取り出し時間の違いは[Amazon S3 Glacierとは？3つのアーカイブストレージクラスと取り出し時間・料金・採用判断を実装者目線で解説](https://www.issoh.co.jp/tech/details/15443/)にあります。

### MIMEタイプの推測と–copy-propsで決まるS3間コピーのメタデータ

アップロード時、CLIは拡張子からMIMEタイプを推測して`Content-Type`に入れます。`--content-type`を指定すれば推測値を上書きでき、`--no-guess-mime-type`で推測そのものを止められます。静的サイトのファイルを配る場合は、拡張子の無いファイルに意図しない型が付いていないかを確認してください。

S3間コピーでは`--copy-props`がメタデータの引き継ぎを決めます。既定の`default`でコピーされる対象は、タグと`Content-Type`・`Cache-Control`・ユーザー定義メタデータなどです。`none`は何もコピーせず、`all`は`default`の範囲に加えてアノテーションも引き継ぎます。マルチパートで処理される大きなオブジェクトでは、`default`がHeadObjectやGetObjectTagging、PutObjectTaggingを追加で呼ぶとリファレンスに書かれており、タグの読み書き権限が無いロールで失敗するのは、この追加呼び出しが原因です。`--metadata-directive`を指定すると`--copy-props`は無効になる点にも注意が要ります。リージョンをまたぐS3間コピーでは、コピー元のリージョンを`--source-region`で渡します（`--region`はコピー先を指します）。

## ACL無効が既定になった後のバケットで–aclが400で失敗する原因と対処

古い記事の`--acl public-read`をそのまま使うと、今のバケットでは失敗します。原因はS3側の既定値の変更です。

### 新規バケットのACL無効の既定値と指定時に400エラーが返る条件

[オブジェクト所有権のドキュメント](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html)によると、新しく作るバケットのObject Ownershipは既定で「Bucket owner enforced」で、ACLはすべて無効です。この状態のバケットが受け付けるのは、ACLを指定しないPUTか、`bucket-owner-full-control`を指定したPUTだけです。それ以外のACLを付けたリクエストは400エラーになり、エラーコード`AccessControlListNotSupported`が返ります。

対処は、ACLで公開する設計をやめてバケットポリシーで権限を渡すことです。公開配信が目的なら、CloudFrontを前段に置く構成が素直でしょう。権限の組み立ては[AWS IAMとは？仕組み・ユーザー/ロール/ポリシーの違いと権限設計のベストプラクティスを実装者目線で解説](https://www.issoh.co.jp/tech/details/15427/)を参照してください。

### 他アカウントのバケットへ書き込む既存スクリプトに残せる唯一のACL指定

例外として、他アカウントのバケットへ書き込む既存のスクリプトは`--acl bucket-owner-full-control`を付けたままでも動きます。ACLが無効なバケットでもこの指定は受け付けられ、書き込んだオブジェクトの所有者は書き込み先のバケット所有者です。なお`--acl`を使う場合、実行するIAMプリンシパルに`s3:PutObjectAcl`の権限が要ることもリファレンスに書かれています。

## 終了コード1と2を区別してシェルスクリプトとCIで失敗を検知する書き方

`aws s3 cp`をバッチやCIに組み込むなら、終了コードの意味を押さえておく必要があります。

### 終了コード0・1・2・252〜255が示す失敗の種類と確認方法

[終了コードのドキュメント](https://docs.aws.amazon.com/cli/latest/topic/return-codes.html)にある定義を表にまとめます。

| コード | 意味                     |
| --- | ---------------------- |
| 0   | 成功                     |
| 1   | s3コマンドで1件以上の転送が失敗      |
| 2   | 構文の解析失敗、または一部ファイルのスキップ |
| 130 | Ctrl-Cによる中断            |
| 252 | 構文や引数の値が不正             |
| 253 | 設定や認証情報が無い             |
| 254 | サービスがエラーを返した           |
| 255 | その他の実行時エラー             |

注意したいのは2です。s3コマンドでは、存在しないファイル、読み取り権限の無いファイル、FIFOやソケットなどがスキップされたときに2が返り、ほかのファイルは正常に転送されています。全件の失敗とは限りません。

### 夜間バックアップでスキップを許容するか失敗にするかを分岐させるシェルの書き方

夜間バックアップのように「スキップは警告、転送失敗は異常」と分けたい場合は、終了コードで分岐させます。

```
#!/usr/bin/env bash
set -u
aws s3 cp ./export s3://example-backup/export/ --recursive --only-show-errors
rc=$?
case "$rc" in
  0) echo "転送完了" ;;
  2) echo "一部ファイルをスキップしました（権限や特殊ファイルを確認）" >&2 ;;
  1) echo "転送に失敗したファイルがあります" >&2; exit 1 ;;
  *) echo "CLIの実行エラー rc=$rc" >&2; exit "$rc" ;;
esac
```

`--only-show-errors`はエラーと警告だけを出すオプションで、ログが進捗表示で埋まるのを防げます。PowerShellで同じ終了コードの判定に使う変数は、`$LASTEXITCODE`です。Glacier系のオブジェクトを含む再帰コピーでは、取り出せないオブジェクトの警告で2が返ることがあります。`--ignore-glacier-warnings`を付ければ警告が消え、終了コードも2になりません。

## 転送が遅いときに見直すマルチパート設定とCRT転送クライアントの条件

大量のファイルや大きなファイルで時間がかかる場合、触るのはコマンドの引数ではなく`~/.aws/config`の転送設定です。

### 同時リクエスト10・閾値8MBの既定値を変える設定ファイルの例

[CLIのS3設定](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html)の既定値は、同時リクエスト数10、キュー1,000、マルチパート閾値8MB、チャンクサイズ8MB、帯域上限なしです。小さいファイルが大量にあるなら同時リクエスト数を、大きいファイルが少数ならチャンクサイズを上げます。

```
[profile batch]
region = ap-northeast-1
s3 =
  max_concurrent_requests = 32
  multipart_threshold = 64MB
  multipart_chunksize = 32MB
  max_bandwidth = 200MB/s
```

同時リクエストを増やすと、そのぶんCPUとネットワークを食います。業務時間中に共有回線で動かすなら`max_bandwidth`で上限を付けておくと、ほかの通信を圧迫しません。PUTやGETの回数はリクエスト料金に直結するため、細かいファイルを大量に転送する前に[S3の料金を実額で計算する｜東京リージョンの単価内訳とコストを下げる設定手順](https://www.issoh.co.jp/tech/details/17537/)で単価を確認しておくと安心です。

### preferred\_transfer\_clientのcrt切替条件と無視される設定

同じページによると、`preferred_transfer_client`の既定は`auto`です。S3間コピーではないこと、Linux上のEC2で動いていること、対象のインスタンスタイプであること、ほかにCRTを使うCLIプロセスが動いていないこと。これらを満たすと、C言語ベースのCRT転送クライアントへ自動で切り替わります。

CRTが使われると`max_queue_size`と`max_bandwidth`は無視され、帯域は`target_bandwidth`で指定します。手元のPCでは効いていた帯域制限がEC2上で効かない、という差はここから生まれます。挙動を揃えたいなら`preferred_transfer_client = classic`を明示してください。

転送の正しさについては、[オブジェクト整合性のドキュメント](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html)にある通り、AWSのクライアントはアップロード時にチェックサムを計算して送り、S3側で照合します。既定のアルゴリズムはCRC64NVMEです。ダウンロード時にも検証したい場合は`--checksum-mode ENABLED`を付けます。

## aws s3 cpとsync・S3 Batch Operationsの選択基準

最後に、`cp`を選ぶ条件と別の手段へ寄せる場面を線引きします。

### 受託開発の現場でcpを第一候補にする条件と見送るべき3つの場面

第一候補にする条件は、転送対象がその都度決まること、1回きりか毎回すべて送り直してよいこと、パイプで受け渡したいことの3つです。ダンプの退避、ビルド成果物の配置、調査用の一時ダウンロードがこれに当たります。

見送る場面は3つあります。1つ目は、同じディレクトリを繰り返し送る運用です。[syncのリファレンス](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html)にある通り`sync`はサイズと更新時刻で差分を判定するため、変更分だけを送れます。2つ目は、数百万件単位のオブジェクトを一度に扱う場合です。CLIの1プロセスで回すより、S3 Batch Operationsに任せたほうが再実行と進捗の管理が楽になります。3つ目は、アプリケーションがファイルシステムとして読み書きしたい場合です。[S3 Filesとは：S3バケットをNFSでマウントする手順とEFS・Mountpointとの使い分け](https://www.issoh.co.jp/tech/details/17786/)のようにマウントする構成を検討します。

転送設計を含めてバックアップや配信の構成を固めたい場合は、[インフラ構築（AWS・Google Cloud・Azure）](https://www.issoh.co.jp/service/system/aws/)で要件整理から対応しています。

## よくある質問

aws s3 cpについて検索されている質問に、公式ドキュメントの記載をもとに答えます。

### aws s3 cpでワイルドカードを使って複数ファイルを指定できますか？

パスにワイルドカードは書けません。`--recursive`でディレクトリごと対象にしたうえで、`--exclude "*" --include "*.csv"`のようにフィルタで絞ります。後に書いたフィルタが優先されるため、除外を先、取り込みを後に書くのが基本形です。

### aws s3 cpとaws s3 syncはどう使い分けますか？

`cp`は指定したものを毎回コピーし、`sync`はサイズと更新時刻を比べて差分だけを転送します。1回きりの転送やパイプでの受け渡しは`cp`、同じディレクトリを繰り返し反映する運用は`sync`が向きます。`sync`に`--delete`を付けると転送先にしか無いファイルを消すので、先に`--dryrun`で確認してください。

### aws s3 cpでフォルダごとダウンロードするにはどうすればよいですか？

`aws s3 cp s3://example-bucket/reports/ ./reports --recursive`のように、コピー元のプレフィックスに`--recursive`を付けます。WindowsやmacOSへ落とすときは、大文字小文字だけが違うキーが上書きし合わないよう`--case-conflict warn`などの指定も検討してください。

### aws s3 cpで上書きせずに足りないファイルだけを送れますか？

現行のAWS CLI v2には`--no-overwrite`があり、転送先に存在しないファイルだけを送ります。古いバージョンでは使えない場合があるため、`aws --version`で版を確認し、リファレンスに載っているかを照らしてから使ってください。

### aws s3 cpが一部だけ成功して終了コード2になるのはなぜですか？

s3コマンドの終了コード2は、存在しないファイル、読み取り権限の無いファイル、FIFOやソケットなどがスキップされたことを示します。スキップされたファイル以外は正常に転送された状態です。転送そのものが失敗した場合は1が返るので、スクリプトでは1と2を分けて扱うと原因を切り分けやすくなります。

## 関連記事

- [AWS S3の使い方｜CLIでのバケット作成から権限設計・署名付きURLまでの実装手順](https://www.issoh.co.jp/tech/details/17489/)：バケット作成・権限設計・署名付きURLまでの全体手順。
- [AWS CLIの導入と運用｜v2の設定・SSO認証・v1サポート終了への移行手順](https://www.issoh.co.jp/tech/details/17403/)：本記事のコマンドを動かす前段の環境構築。
- [Amazon S3とは？オブジェクトストレージの仕組み・ストレージクラスと料金・採用判断を実装者目線で解説](https://www.issoh.co.jp/tech/details/15433/)：–storage-classで選ぶクラスの考え方。
- [S3の料金を実額で計算する｜東京リージョンの単価内訳とコストを下げる設定手順](https://www.issoh.co.jp/tech/details/17537/)：大量転送で効くリクエスト料金の単価。
- [S3 Filesとは：S3バケットをNFSでマウントする手順とEFS・Mountpointとの使い分け](https://www.issoh.co.jp/tech/details/17786/)：コピーではなくマウントで扱う場合の選択肢。

---

出典: [aws s3 cpの使い方｜再帰コピー・フィルタ・ストリーム転送と終了コードの実装手順](<https://www.issoh.co.jp/tech/details/18008/>)（株式会社一創）
