AWS EmulatorでS3にファイルを置いて取り出す方法
AWS Emulator を手元で動かすと、AWS のアカウントがなくても、AWS CLI で S3 のバケットを作り、ファイルをアップロードしてダウンロードできます。ローカル環境での開発やテスト、CI で、本物の S3 にファイルを置かずにアップロードやダウンロードの処理を試したいときの手順です。バケットの作成、ファイルの置き方と取り出し方、一覧やメタデータの見方、後片付けまでを、検証環境で実行したコマンドと出力のまま載せます。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.385(2026年11月14日リリース)、AWS CLI 2.40.3 です。AWS のアカウントと認証情報は使っていません。本物の S3 での動き(料金、速さ、ほかのアカウントとのバケット名の重なりなど)は確かめていません。本物の S3 について書いているところは、公式ドキュメントを出どころにしています。
エミュレーターを起動して、AWS CLI を向ける
AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。公式ドキュメントによると、AWS のアカウントは要らず、追加の料金もかかりません。リクエストは AWS に送られず、エミュレーターの中に作られたリソースを相手にします。
入れ方は別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱うので、ここでは短くします。Linux 向けの手順にある Debian パッケージを、gpg で署名を確かめてから apt-get install で入れました。私は root で作業したので実際には sudo を付けていませんが、下のコマンドでは一般のユーザー向けに sudo を付けています。
curl -fsSLO https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator_amd64.deb
起動は aws-emulator です。-t off は、エミュレーターが既定で AWS に送る利用状況のデータ(テレメトリー)を切る指定です。エミュレーターはその端末で動き続けるので、AWS CLI は別の端末で使います。
aws-emulator -t off
別の端末で、公式ドキュメントにある環境変数を設定します。エミュレーターは 127.0.0.1:9297 で待ち受け、~/.aws/emulator/9297/ に、この起動でだけ使えるアクセスキーと設定ファイル、証明書を書き出します。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
公式ドキュメントでは、AWS_ENDPOINT_URL が設定されていないシェルでコマンドを実行すると、見つかった認証情報を使って本物の AWS に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数がすべて設定されたシェルで実行してください。
エミュレーターに繋がっていれば、aws sts get-caller-identity の ARN のユーザー名が emulator になります(12桁のアカウントIDは置き換えています)。
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
バケットを作る
AWS CLI には、S3 を操作するコマンドが2系統あります。ファイルのコピーのように書ける aws s3 と、S3 の API をそのまま呼ぶ aws s3api です。バケットはどちらでも作れます。aws s3 mb は短く書けて、aws s3api create-bucket は API の応答をそのまま返します。
$ aws s3 ls
$ aws s3 mb s3://example-bucket
make_bucket: example-bucket
$ aws s3api create-bucket --bucket example-bucket-2
{
"Location": "/example-bucket-2",
"BucketArn": "arn:aws:s3:::example-bucket-2"
}
$ aws s3 ls
2026-11-15 01:28:46 example-bucket
2026-11-15 01:28:47 example-bucket-2
起動した直後は、aws s3 ls を実行しても何も表示されません。バケットを作ると、作った日時と名前が並びます。
バケットの名前には決まりがあります。バケットの命名規則によると、使えるのは小文字の英字、数字、ピリオド、ハイフンで、長さは3〜63文字です。大文字とアンダースコアの入った名前を指定すると、エミュレーターも InvalidBucketName で断りました。終了コードは 254 です。
$ aws s3api create-bucket --bucket Example_Bucket
aws: [ERROR]: An error occurred (InvalidBucketName) when calling the CreateBucket operation: The specified bucket is not valid.
同じ名前のバケットをもう一度作ろうとすると、エラーにならず、最初と同じ応答が返りました。CreateBucket の API リファレンスには、自分が持っているバケットを作り直したとき、米国東部(バージニア北部、us-east-1)だけは昔との互換のために 200 OK を返し、ほかのリージョンでは BucketAlreadyOwnedByYou を返すと書かれています。検証環境は us-east-1 を使っているので、この説明と同じ結果です。
$ aws s3api create-bucket --bucket example-bucket
{
"Location": "/example-bucket",
"BucketArn": "arn:aws:s3:::example-bucket"
}
us-east-1 以外のリージョンに作るとき
us-east-1 以外のリージョンに作るときは、--create-bucket-configuration LocationConstraint=<リージョン> を付けます。API リファレンスによると、指定しなければ us-east-1 に作られます。
リクエストを送るリージョンが us-east-1 のまま LocationConstraint=us-west-2 を指定すると、エミュレーターは IllegalLocationConstraintException で断りました。AWS_REGION=us-west-2 を付けて実行すると作れて、get-bucket-location で us-west-2 が返りました。
$ aws s3api create-bucket --bucket example-bucket-west --create-bucket-configuration LocationConstraint=us-west-2
aws: [ERROR]: An error occurred (IllegalLocationConstraintException) when calling the CreateBucket operation: The us-west-2 location constraint is incompatible for the region specific endpoint this request was sent to.
$ AWS_REGION=us-west-2 aws s3api create-bucket --bucket example-bucket-west --create-bucket-configuration LocationConstraint=us-west-2
{
"Location": "https://127.0.0.1:9297/example-bucket-west/",
"BucketArn": "arn:aws:s3:::example-bucket-west"
}
$ aws s3api get-bucket-location --bucket example-bucket-west
{
"LocationConstraint": "us-west-2"
}
us-east-1 のバケットでは、get-bucket-location の値は null でした。また、LocationConstraint=us-east-1 と明示すると、InvalidLocationConstraint で断られました。us-east-1 に作るときは、この指定を付けずに作ります。
ただし、us-west-2 のバケットは、us-east-1 のシェルで実行した aws s3 ls にも並びました。公式ドキュメントによると、エミュレーターはリージョンやアカウントごとにリソースを分けておらず、リクエストは1つのリージョンと1つのアカウントで送るよう案内されています。複数のリージョンを試すときは、リージョンごとに別のポートでエミュレーターを起動するように、とのことです。以降は us-east-1 の example-bucket を使います。
ファイルを置く
ファイルを1つ置くときは aws s3 cp です。置き先を s3://バケット名/ で終えると、ファイル名がそのままキー(オブジェクトの名前)になります。--no-progress は、転送の進み具合の表示を消すオプションです。付けないと、Completed ... で始まる進み具合の行も出力に混ざります。
$ aws s3 cp --no-progress hello.txt s3://example-bucket/
upload: ./hello.txt to s3://example-bucket/hello.txt
フォルダーの中身をまとめて置くときは --recursive を付けます。photos/ の下の2つのファイルが、photos/cat1.jpg のようなキーで置かれました。
$ aws s3 cp --no-progress photos/ s3://example-bucket/photos/ --recursive
upload: photos/cat1.jpg to s3://example-bucket/photos/cat1.jpg
upload: photos/cat2.jpg to s3://example-bucket/photos/cat2.jpg
Content-Type や独自のメタデータを決めて置くときは、aws s3api put-object も使えます。--body に置くファイルを、--key にキーを指定します。応答には ETag が返ります。
$ aws s3api put-object --bucket example-bucket --key notes/memo.json --body hello.txt --content-type application/json --metadata author=tama
{
"ETag": "\"62dedf873d7afac717e8b0ef7c7b4db8\"",
"ChecksumCRC64NVME": "DkMOL0Pg1W8=",
"ChecksumType": "FULL_OBJECT",
"ServerSideEncryption": "AES256"
}
aws s3 cp にも --content-type と --metadata のオプションがあります。cp のリファレンスによると、指定しないときは、Content-Type を推測して付けます。
最後に、20MiB(20,971,520バイト)のファイルを置きました。出力の見た目は小さいファイルと同じです。
$ aws s3 cp --no-progress big.bin s3://example-bucket/big.bin
upload: ./big.bin to s3://example-bucket/big.bin
置いたファイルの一覧を出す
aws s3 ls s3://バケット名/ は、バケットの直下だけを表示します。/ で区切られたキーは、PRE(プレフィックス)の行にまとめて出ます。S3 のフォルダーの説明によると、S3 のバケットは階層のない平らな構造で、フォルダーは、キーの頭の共通部分(プレフィックス)でオブジェクトをまとめて見せているものです。
$ aws s3 ls s3://example-bucket/
PRE notes/
PRE photos/
2026-11-15 01:28:58 20971520 big.bin
2026-11-15 01:28:55 10 hello.txt
--recursive を付けると全部のキーを、さらに --human-readable --summarize を付けると、読みやすい大きさと合計を表示します。
$ aws s3 ls s3://example-bucket/ --recursive --human-readable --summarize
2026-11-15 01:28:58 20.0 MiB big.bin
2026-11-15 01:28:55 10 Bytes hello.txt
2026-11-15 01:28:57 10 Bytes notes/memo.json
2026-11-15 01:28:56 293.0 KiB photos/cat1.jpg
2026-11-15 01:28:56 195.3 KiB photos/cat2.jpg
Total Objects: 5
Total Size: 20.5 MiB
スクリプトで使うなら、JSON で返る aws s3api list-objects-v2 が扱いやすいです。--prefix で、キーの頭が合うものだけに絞れます。
$ aws s3api list-objects-v2 --bucket example-bucket --prefix photos/ --query "Contents[].{Key: Key, Size: Size}"
[
{
"Key": "photos/cat1.jpg",
"Size": 300000
},
{
"Key": "photos/cat2.jpg",
"Size": 200000
}
]
置いたファイルの情報を確かめる
中身を取り出さずに、大きさや Content-Type、メタデータだけを見るときは aws s3api head-object です。aws s3 cp で置いた hello.txt は、Content-Type が拡張子から推測された text/plain になっていました。
$ aws s3api head-object --bucket example-bucket --key hello.txt
{
"AcceptRanges": "bytes",
"LastModified": "2026-11-15T01:28:55+00:00",
"ContentLength": 10,
"ETag": "\"62dedf873d7afac717e8b0ef7c7b4db8\"",
"ContentType": "text/plain",
"ServerSideEncryption": "AES256",
"Metadata": {}
}
$ md5sum hello.txt
62dedf873d7afac717e8b0ef7c7b4db8 hello.txt
ETag は、手元のファイルの MD5 と同じ値でした。put-object で置いた notes/memo.json では、指定した application/json と author: tama が返りました。
$ aws s3api head-object --bucket example-bucket --key notes/memo.json
{
"AcceptRanges": "bytes",
"LastModified": "2026-11-15T01:28:57+00:00",
"ContentLength": 10,
"ETag": "\"62dedf873d7afac717e8b0ef7c7b4db8\"",
"ContentType": "application/json",
"ServerSideEncryption": "AES256",
"Metadata": {
"author": "tama"
}
}
20MiB のファイルの ETag は、MD5 の形ではなく、末尾に -3 が付いていました。
$ aws s3api head-object --bucket example-bucket --key big.bin --query "{ContentLength: ContentLength, ETag: ETag}"
{
"ContentLength": 20971520,
"ETag": "\"1741f30c0b00ff69ca5e6c69fa9739dc-3\""
}
AWS CLI の S3 の設定のページによると、aws s3 のコマンドは、ファイルが multipart_threshold(既定は 8MB)以上だと、マルチパートアップロードで分けて送ります。分ける大きさの multipart_chunksize も既定は 8MB なので、20MiB は3つに分かれます。S3 の Object の説明には、マルチパートアップロードで作ったオブジェクトの ETag は MD5 ではないと書かれています。ファイルが壊れていないかを ETag と MD5 で比べる処理は、マルチパートアップロードで置いたファイル(aws s3 では既定で 8MB 以上)には使えません。
ServerSideEncryption の AES256 は、サーバー側の暗号化(SSE-S3)を表します。既定の暗号化の FAQ によると、本物の S3 でも、2023年1月5日から、新しく置くオブジェクトは既定で SSE-S3 で暗号化され、応答の x-amz-server-side-encryption ヘッダーで確かめられます。
ファイルを取り出す
取り出すときも aws s3 cp で、置くときと引数の順番を逆にします。置き先に - を指定すると、ファイルに保存せずに標準出力に出します。
$ aws s3 cp s3://example-bucket/hello.txt -
にゃー
$ aws s3 cp --no-progress s3://example-bucket/hello.txt downloaded.txt && cat downloaded.txt
download: s3://example-bucket/hello.txt to ./downloaded.txt
にゃー
aws s3api get-object では、最後の引数に保存先のファイル名を書きます。中身はファイルに保存され、画面にはメタデータが JSON で出ます。
$ aws s3api get-object --bucket example-bucket --key notes/memo.json memo.json
{
"AcceptRanges": "bytes",
"LastModified": "2026-11-15T01:28:57+00:00",
"ContentLength": 10,
"ETag": "\"62dedf873d7afac717e8b0ef7c7b4db8\"",
"ChecksumCRC64NVME": "DkMOL0Pg1W8=",
"ChecksumType": "FULL_OBJECT",
"ContentType": "application/json",
"ServerSideEncryption": "AES256",
"Metadata": {
"author": "tama"
}
}
$ cat memo.json
にゃー
プレフィックスの下をまとめて取り出すときは、置くときと同じく --recursive を付けます。ls -l の持ち主の列は user に置き換えています。
$ mkdir dl && aws s3 cp --no-progress s3://example-bucket/photos/ dl/photos/ --recursive && ls -l dl/photos
download: s3://example-bucket/photos/cat2.jpg to dl/photos/cat2.jpg
download: s3://example-bucket/photos/cat1.jpg to dl/photos/cat1.jpg
total 492
-rw-r--r-- 1 user user 300000 Nov 15 01:28 cat1.jpg
-rw-r--r-- 1 user user 200000 Nov 15 01:28 cat2.jpg
取り出したファイルが、置いたものと同じかを SHA-256 で比べました。マルチパートで送った 20MiB のファイルも、写真の代わりに置いたランダムなバイト列も、同じ値になりました。
$ aws s3 cp --no-progress s3://example-bucket/big.bin dl/big.bin
download: s3://example-bucket/big.bin to dl/big.bin
$ sha256sum big.bin dl/big.bin photos/cat1.jpg dl/photos/cat1.jpg
c0de17abc664c478bc1e8c5494955a1ae1167389c6109f38f66245f6ef183e58 big.bin
c0de17abc664c478bc1e8c5494955a1ae1167389c6109f38f66245f6ef183e58 dl/big.bin
e391abf9c8acbb9cda9b32a44c340cdf0ca623494a6b3bccf3b004808b6d2cc2 photos/cat1.jpg
e391abf9c8acbb9cda9b32a44c340cdf0ca623494a6b3bccf3b004808b6d2cc2 dl/photos/cat1.jpg
一部だけを取り出すときは、get-object の --range にバイトの範囲を指定します。先頭の10バイトを取り出すと、ContentRange に範囲と全体の大きさが返り、手元のファイルの先頭10バイトと同じでした。
$ aws s3api get-object --bucket example-bucket --key big.bin --range bytes=0-9 part.bin --query "{ContentRange: ContentRange, ContentLength: ContentLength}"; cmp part.bin <(head -c 10 big.bin) && echo same
{
"ContentRange": "bytes 0-9/20971520",
"ContentLength": 10
}
same
AWS CLI を使わずに curl で取り出す
aws s3 presign は、署名付き URL を作ります。presign のリファレンスによると、この URL を受け取った人は誰でも、HTTP の GET でオブジェクトを取り出せます。--expires-in は有効な秒数で、既定は 3600秒、最大は 604800秒(7日)です。
エミュレーターでは、URL の向き先が https://127.0.0.1:9297/バケット名/キー になりました。次のコマンドは、URL を作って変数に入れ、アクセスキーと署名の部分を sed で伏せて表示してから、curl で取り出しています。curl には、エミュレーターの証明書を --cacert で渡します。
$ URL=$(aws s3 presign s3://example-bucket/hello.txt --expires-in 300); echo "$URL" | sed -E "s/(X-Amz-Credential=)[^&]+/\1<省略>/; s/(X-Amz-Signature=)[^&]+/\1<省略>/"; curl -sS --cacert "$AWS_CA_BUNDLE" "$URL"
https://127.0.0.1:9297/example-bucket/hello.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<省略>&X-Amz-Date=20261115T012910Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=<省略>
にゃー
署名のない同じ URL に curl でアクセスすると、HTTP の 403 が返りました。
$ curl -sS -o /dev/null -w "%{http_code}\n" --cacert "$AWS_CA_BUNDLE" https://127.0.0.1:9297/example-bucket/hello.txt
403
無いキーを指定したときのエラー
aws s3api get-object で無いキーを指定すると NoSuchKey になり、終了コードは 254 でした。
$ aws s3api get-object --bucket example-bucket --key no-such.txt out.txt
aws: [ERROR]: An error occurred (NoSuchKey) when calling the GetObject operation: The specified key does not exist.
aws s3 cp では、エラーは HeadObject の 404 で、終了コードは 1 でした。エミュレーターでは、バケットの名前を間違えたときも、同じ Key "hello.txt" does not exist というメッセージでした。キーが無いと出たときは、バケットの名前が合っているかも確かめてください。
$ aws s3 cp s3://example-bucket/no-such.txt .
fatal error: An error occurred (404) when calling the HeadObject operation: Key "no-such.txt" does not exist
$ aws s3 cp s3://no-such-bucket-example/hello.txt .
fatal error: An error occurred (404) when calling the HeadObject operation: Key "hello.txt" does not exist
上書きと削除
同じキーにもう一度置くと、何も聞かれずに上書きされます。hello.txt を別の内容で置き直すと、取り出したときの中身も変わりました。
$ printf "みゃー\n" > hello2.txt; aws s3 cp --no-progress hello2.txt s3://example-bucket/hello.txt && aws s3 cp s3://example-bucket/hello.txt -
upload: ./hello2.txt to s3://example-bucket/hello.txt
みゃー
消すときは aws s3 rm です。消したあとにもう一度同じキーを消しても、エミュレーターではエラーにならず、同じ delete: の行が出ました。
$ aws s3 rm s3://example-bucket/hello.txt
delete: s3://example-bucket/hello.txt
$ aws s3 rm s3://example-bucket/hello.txt
delete: s3://example-bucket/hello.txt
中身が残っているバケットは、aws s3 rb で消せません。プレフィックスの下を rm --recursive で消すか、rb --force で中身ごと消します。
$ aws s3 rb s3://example-bucket
remove_bucket failed: s3://example-bucket An error occurred (BucketNotEmpty) when calling the DeleteBucket operation: The bucket you tried to delete is not empty
$ aws s3 rm s3://example-bucket/photos/ --recursive
delete: s3://example-bucket/photos/cat1.jpg
delete: s3://example-bucket/photos/cat2.jpg
$ aws s3 rb s3://example-bucket --force
delete: s3://example-bucket/big.bin
delete: s3://example-bucket/notes/memo.json
remove_bucket: example-bucket
rb のリファレンスによると、--force はバケットの中のオブジェクトをすべて消してからバケットを消します。バージョニングを有効にしたバケットでは、古いバージョンは消えないので、バケットの削除は失敗すると書かれています。
エミュレーターを止めると、バケットもファイルも消える
公式ドキュメントによると、エミュレーターはリソースをすべてメモリーに置き、止めると消します。検証環境で、バケットが2つ残ったままエミュレーターに SIGTERM を送り、もう一度 aws-emulator -t off で起動すると、aws s3 ls には何も表示されませんでした。置いたファイルを次の起動まで残しておく使い方はできないので、テストのたびにバケットを作るところから準備します。この使い方は、別の記事「AWS Emulatorでテストのたびに空の状態から始める方法」で扱っています。
AWS は、エミュレーターの動きを本物と比べているのは米国西部(オレゴン、us-west-2)リージョンだけだとしています。グローバルなサービスは us-east-1 で比べていますが、S3 については、この記事で使った us-east-1 は比べているリージョンではありません。サービスごとの忠実度のスコアは、リリースのたびに GitHub のリリースページに載ります。




