結論
LocalStack(ローカルスタック)は、S3・SQS・Lambda などの AWS のサービスを、手元の Docker の中で再現するエミュレーターです。AWS CLI や SDK の接続先(エンドポイント)を http://localhost:4566 などに向けるだけで、本物の AWS に触れずに開発やテストができます。2026年3月23日から無料の Community 版の提供の形が変わり、今は無料の Hobby プランも含めてアカウントと認証トークンが要ります(2026年11月18日時点)。
この記事でわかること
- LocalStack の仕組み・対応サービス・料金(Hobby・Base・Ultimate・Enterprise)と2026年の変更点
- lstk・Docker でのインストール、認証トークン、awslocal と
--endpoint-urlの使い方 - boto3 で S3・SQS を手元のエミュレーターに向けた実行結果、moto との違い、症状表と判断表
この記事で実際に動かしたもの:moto 5.2.5 のサーバーモード(127.0.0.1:5000)に boto3 1.44.5・AWS CLI 1.46.3・awslocal 0.23.0 を向けた S3・SQS の操作、エラーの再現、pytest、1回あたりの処理時間の計測。LocalStack 本体は Docker のデーモンが使えないため動かしておらず、アカウントの作成・認証トークンの利用もしていません。
LocalStack を使うときの流れを図にすると次のようになります。アプリのコードはそのままで、接続先だけが変わります。
flowchart TD
A[アプリのコード<br>boto3・CLI] --> B{接続先}
B -->|本番| C[本物の AWS]
B -->|テスト| D[localhost:4566<br>LocalStack]
D --> E[S3・SQS などを<br>手元で再現]
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| LocalStack とは | AWS のサービスを手元のコンテナで再現するエミュレーター | LocalStackとは |
| LocalStack は無料か | 無料の Hobby プランがある。ただし提供元の説明では非商用向けで、アカウントが要る | LocalStackの料金と無料プラン |
| LocalStack の料金 | Base は年払いで1ライセンス月39 USD(月払い45 USD)、Ultimate は年払いで月89 USD | LocalStackの料金と無料プラン |
| 対応サービス | 公式のサービス一覧に約100。Hobby は30以上、Base は55以上、Ultimate は110以上 | LocalStackの対応サービス |
| LocalStack のインストール | 新しい CLI の lstk か、Docker の localstack/localstack イメージ |
LocalStackのインストール方法 |
| 認証トークンは必要か | 必要。LOCALSTACK_AUTH_TOKEN で渡すか、lstk のブラウザーのログインで設定 |
認証トークンの設定と確かめ方 |
| awslocal の使い方 | aws の代わりに打つと接続先を自動で付ける。今は非推奨で lstk aws が後継 |
awslocalと--endpoint-urlの使い方 |
| moto との違い | moto は Python のライブラリ(サーバーにもなる)、LocalStack は Docker で動く別の製品 | LocalStackとmotoの違い |
| LocalStack に繋がらない | コンテナが動いていない・ポートが違う・トークンが無効、の順に確かめる | よくあるエラー/つまずき |
確認環境:Ubuntu 24.04.5 LTS の上の Python 3.13.18 で、moto 5.2.5(サーバーモード、127.0.0.1:5000 だけで待ち受け)、boto3/botocore 1.44.5、AWS CLI 1.46.3(v1)、awscli-local 0.23.0、pytest 9.2.0 を使い、S3 と SQS の作成・送受信・エラーの再現・pytest・処理時間の計測を行いました。AWS の本物の認証情報は環境変数ごと外し、ダミーの値(test)だけを使っています。Python の接続先を 127.0.0.1 以外に出さない仕掛けを入れて動かし、本物の AWS のエンドポイントには送っていません。LocalStack 本体(コンテナ・lstk・LocalStack Desktop)は Docker のデーモンが使えないため動かしておらず、アカウントの作成・認証トークンの利用・購入もしていません。LocalStack の仕組み・料金・対応サービス・インストール・認証トークン・エラーの文言は、LocalStack の公式ドキュメント(docs.localstack.cloud)・料金ページ・公式ブログで1つずつ確かめました。図は mermaid で描画を確かめています(確認日 2026年11月18日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「LocalStackとは|AWSを手元で再現する使い方・料金・対応サービス」
LocalStackとは(AWSを手元で再現するエミュレーター)
この節では、LocalStack が何をするもので、どんな場面で使われるのかが分かります。
LocalStack は、AWS の API を受け付けて、本物の AWS と同じ形の応答を返すソフトウェアです。 公式ドキュメントのサービス一覧は「LocalStack がサポートし、開発環境でエミュレートする AWS のサービス」と説明しています。製品名は今は「LocalStack for AWS」で、同じ会社が Snowflake 向け・Azure 向け(プレビュー)のエミュレーターも出しています。
コードは本物の AWS 向けのまま、接続先の URL だけを手元に向けます。AWS CLI・各言語の SDK・Terraform・AWS CDK・AWS SAM・Pulumi・Testcontainers との連携が公式ドキュメントに並んでいます。
1お金と待ち時間を減らす
何度作っても AWS の料金はかからず、作成や削除の待ち時間も短い。
2本番に触れない
手元のコンテナの中で完結するので、操作を誤っても本番のデータは変わらない。テストのたびに空の状態から始められる。
3CI でも同じ環境
同じイメージを CI のジョブで起動し、結合テストを流せる。2026年からは CI の利用回数の制限がなくなった(公式ブログ)。
LocalStackの仕組み:1つのコンテナとポート4566
LocalStack は Docker のコンテナとして動き、すべてのサービスの API を1つの入り口(ゲートウェイ)のポート 4566 で受け付けます。 インストールの公式ページは、Docker で動かすときに 4566 と 4510-4559 と 443 のポートを 127.0.0.1 に割り当て、Docker のソケット(/var/run/docker.sock)を渡す例を載せています。ソケットは、Lambda の関数などを別のコンテナで動かすときに使われます。
動いているかは、ゲートウェイの /_localstack/health で確かめます。公式の確かめ方は次のとおりです。
curl http://localhost:4566/_localstack/health | jq
Lambda の関数そのものの仕組みと料金は記事「AWS Lambdaとは|仕組み・料金の計算・できることと向かない処理」、S3 の料金とストレージクラスは記事「Amazon S3とは|料金・ストレージクラスの選び方を東京の単価で試算」で扱っています。LocalStack はそれらを本物に置く前に、手元で動きを確かめるための道具です。
LocalStackの対応サービスと使える範囲
この節では、LocalStack でどの AWS のサービスが使えるのかと、プランによる違いが分かります。
公式ドキュメントのサービス一覧には、S3・SQS・SNS・DynamoDB・Lambda・API Gateway・CloudFormation・IAM・KMS・Secrets Manager・Step Functions・EventBridge・EC2・ECS・EKS・RDS など、約100のサービスが載っています(2026年11月18日時点に一覧を数えた値。ページ自体は総数を書いていません)。ただし、使えるサービスの数はプランで変わります。料金ページの記載は次のとおりです。
| プラン | エミュレートされるサービス | おもな違い(料金ページの記載) |
|---|---|---|
| Hobby(無料) | 30以上 | 個人のサンドボックス1つ・CI でのテスト・VS Code 連携。状態の保存(永続化)は無し |
| Base | 55以上 | 状態の保存と管理・基本的な IAM ポリシーの適用・Cloud Pods 300MB |
| Ultimate | 110以上 | 高度な IAM ポリシーのテスト・本物の AWS のリソースを写す機能・Cloud Pods 3GB |
| Enterprise | すべての AWS のサービスと機能 | Kubernetes での提供・SSO・GovCloud・オフラインでの提供など |
個々のサービスのページには、どのプランから使えるかが書かれています(SQS と S3 はどちらも Hobby プランから)。使うサービスのページで、プランと API の対応範囲(API Coverage)を確かめるのが確実です。
「一覧に載っている」は「本物と全く同じに動く」という意味ではありません。 後の節で示すように、エミュレーターでは通るのに本物では断られる操作があります。本番に出す前には、本物の AWS の検証用アカウントでも確かめる、という前提で使います。
LocalStackの料金と無料プラン(2026年3月からの変更)
この節では、LocalStack の今のプランと料金、2026年に変わった提供の形が分かります。
2026年3月23日から、LocalStack for AWS は1つのイメージにまとめられ、起動にはアカウントと認証トークンが必要になりました。 公式ブログ「Important Updates to Pricing & Packaging for LocalStack for AWS」は、この日から Community 版のサポートを終えると書いています。同じく公式ブログ「The Road Ahead for LocalStack」によると、変わった点は次のとおりです。
イメージが1つになった
localstack/localstack と localstack/localstack-pro は同じ中身のイメージになった。
起動に認証トークンが要る
トークンを設定せずに最新版を起動すると、トークンを求められる。CI では CI 用のトークンを使う。
GitHub のリポジトリは残る
公開のリポジトリは残り、活動していない(inactive)と明記された。参照用の位置づけになる。
以前の版のタグは使える
以前の版のタグは、認証なしで手元でも CI でも動かせる。ただし、その版に更新や安全面の修正は届かない。
料金ページ(2026年11月18日時点)の価格は次のとおりです。価格は1ライセンス(1人)あたりで、米ドルです。
| プラン | 年払い(月あたり) | 月払い | 対象(料金ページ・ブログの説明) |
|---|---|---|---|
| Hobby | 無料 | 無料 | 趣味など非商用の利用。アカウントの作成が要る |
| Base | 39 USD | 45 USD | 個人の開発者・小さなチーム。カードで購入 |
| Ultimate | 89 USD | 記載なし(月払いは AWS Marketplace) | 商用で開発するチーム |
| Enterprise | 個別見積もり | 個別見積もり | 大規模な利用 |
料金ページの価格から、1年あたりの費用を Python で計算しました(税や為替は含めていません)。
for n in (1, 5, 10):
a = 39 * 12 * n # Base 年払い
m = 45 * 12 * n # Base 月払い
u = 89 * 12 * n # Ultimate 年払い
print(n, a, m, m - a, round((m - a) / m * 100, 1), u)
1 468 540 72 13.3 1068
5 2340 2700 360 13.3 5340
10 4680 5400 720 13.3 10680
無料の Hobby は、提供元の説明では非商用の利用に限られています。 料金ページのよくある質問は、商用でソフトウェアを開発するチームには Base・Ultimate・Enterprise を案内しています。会社の仕事で使うときは、提供元の最新の利用条件と所属先の決まりを先に確かめます。新しく使い始める人には、有料プランを30日試せる期間があると公式ブログは書いています。
LocalStackのインストール方法(lstk・Docker・Docker Compose)
この節では、LocalStack を手元に入れて起動する公式の方法と、それぞれの違いが分かります。
今の公式の推奨は、新しい CLI の lstk です。 lstk は Go で作られた LocalStack の CLI で、起動・停止・状態の確認・ログ・lstk aws などをまとめて扱います。どの方法でも、先に Docker が動いていることが前提です(インストールの公式ページ)。
lstk(推奨)
brew install localstack/tap/lstk で入れる(npm の @localstack/lstk・GitHub のバイナリもある)
lstk doctor で事前チェック、lstk start で起動
初回はブラウザーでログインし、トークンは OS のキーリングに保存される
Docker・Docker Compose
localstack/localstack イメージを直接起動する
認証トークンは環境変数 LOCALSTACK_AUTH_TOKEN で渡す
CI やチームで構成をファイルに残したいときに向く
Docker で直接起動する公式の例です。
docker run \
--rm -it \
-p 127.0.0.1:4566:4566 \
-p 127.0.0.1:4510-4559:4510-4559 \
-p 127.0.0.1:443:443 \
-e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
-v /var/run/docker.sock:/var/run/docker.sock \
localstack/localstack
${LOCALSTACK_AUTH_TOKEN:?} は、環境変数が空なら起動せずに止めるシェルの書き方です。ポートを 127.0.0.1: 付きで割り当てているので、同じネットワークのほかの端末からは見えません。Docker Compose でも同じイメージ・ポート・環境変数を docker-compose.yml に書き、docker compose up で起動します。
以前の Python 製の localstack CLI(localstack start など)は、移行ガイドで非推奨とされ、今後はサポートされないと書かれています。対応する lstk のコマンドは次のとおりです。
| 以前の localstack CLI | lstk |
|---|---|
localstack start -d | lstk start(または lstk) |
localstack wait | 不要(lstk start が準備できるまで待つ) |
localstack stop | lstk stop |
localstack status docker | lstk status |
localstack logs -f -n 100 | lstk logs --follow --tail 100 |
localstack state reset | lstk reset |
移行ガイドは、両方を同時に動かすとそれぞれが別のコンテナを起動するので、並べて使わないよう勧めています。Docker そのものの入れ方と、有料になる条件は関連記事「Docker Desktopとは|インストール・使い方・有料の条件とエラー対処」で扱っています。
認証トークン(LOCALSTACK_AUTH_TOKEN)の設定と確かめ方
この節では、LocalStack の認証トークンの種類・渡し方・有効になったかの確かめ方が分かります。
認証トークンは、LocalStack のコンテナを起動し、ライセンスの機能を有効にするための必須の資格情報です(認証トークンの公式ページ)。AWS のアクセスキーとは別物で、LocalStack のアカウントの画面で発行します。
| 種類 | 範囲 | 使う場所 |
|---|---|---|
| Developer Token | 個人ごと | 手元の開発用の PC |
| CI Auth Token | ワークスペースごと(管理者が管理) | CI のパイプライン・共有のランナー |
lstk の公式ページは、CI には CI 用のトークンが要り、個人の Developer Token は使えないと書いています。CI では LOCALSTACK_AUTH_TOKEN=<CI のトークン> lstk --non-interactive の形で渡します。トークンは CI のシークレットの機能に入れ、リポジトリのファイルやログに書かないようにします。
有効になったかは、http://localhost:4566/_localstack/info の応答で確かめます。公式ページによると、成功していれば "edition": "pro" と "is_license_activated": true が含まれます。トークンが無い・無効なときに出る文言は、公式ページに次のように載っています。
License activation failed!
The credentials defined in your environment are invalid.
起動のときは api.localstack.cloud に接続してライセンスを確かめます。会社の DNS やプロキシで通らないときは、公式ページは dig api.localstack.cloud で名前を引けるか確かめ、ネットワークの管理者に localstack.cloud の許可を相談する方法を案内しています。届かないときはオフラインの有効化になり、24時間ごとに有効化し直します。
awslocalと--endpoint-urlの使い方(lstk awsへの移行)
この節では、AWS CLI を LocalStack に向ける3つの方法と、awslocal が実際に何をしているのかが分かります。
AWS CLI を手元のエミュレーターに向けるには、--endpoint-url を毎回付けるか、プロファイルに endpoint_url を書くか、ラッパーの lstk aws(以前は awslocal)を使います。 AWS CLI の公式の連携ページは、ダミーの認証情報を環境変数に入れたうえで、次のように打つ例を載せています。
export AWS_ACCESS_KEY_ID="test"
export AWS_SECRET_ACCESS_KEY="test"
export AWS_DEFAULT_REGION="us-east-1"
aws --endpoint-url=http://localhost.localstack.cloud:4566 kinesis list-streams
localhost.localstack.cloud は、LocalStack が用意している 127.0.0.1 を指す名前です(名前を引くには DNS への問い合わせが要ります)。http://localhost:4566 でも同じゲートウェイに届きます。
同じ形を、moto のサーバー(127.0.0.1:5000)に向けて実行した結果が次です。LocalStack に向けるときは、URL の 127.0.0.1:5000 を localhost:4566 に変えるだけです。
$ aws --endpoint-url=http://127.0.0.1:5000 s3 ls
2026-11-18 10:42:58 t666-demo
awslocal は非推奨になった(実際の警告文)
awslocal は pip install awscli-local で入る薄いラッパーで、--endpoint-url を自動で付け、認証情報とリージョンが無ければ test と us-east-1 を補います。 中身のコードを読むと、環境変数 AWS_ENDPOINT_URL があればそれを、無ければ LOCALSTACK_HOST(既定は localhost:4566)を接続先にしていました。公式の「Deprecated Wrapper Scripts」のページは、awslocal・tflocal・samlocal・cdklocal を非推奨とし、引き続き動くこと、後継は lstk aws・lstk terraform・lstk sam・lstk cdk であることを書いています。
awscli-local 0.23.0 を moto のサーバーに向けて動かすと、最初に次の警告が出ました(標準エラー出力)。
============================================================================
WARNING: 'awslocal' is deprecated. Use 'lstk aws' instead.
============================================================================
'awslocal' no longer receives updates.
Get started with 'lstk', the new LocalStack CLI:
https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/
...
Continuing with 'awslocal'...
2026-11-18 10:42:58 t666-demo
警告のあとは通常どおり結果が出ます(コードを読むと DISABLE_DEPRECATION_NOTICE=1 で警告を消せる作りでした)。LocalStack が動いていないときは、次のエラーになります(何も動いていない 4566 に向けた実際の出力)。
Could not connect to the endpoint URL: "http://localhost:4566/"
boto3のendpoint_urlでS3・SQSを手元のエミュレーターに向けて動かす
この節では、Python の boto3 で、S3 と SQS を本物の AWS ではなく手元のエミュレーターに向けて動かしたときの、コードと実際の出力が分かります。
boto3 では、クライアントを作るときに endpoint_url を渡すだけで接続先が変わります。 LocalStack の boto3 の公式ページは endpoint_url = "http://localhost.localstack.cloud:4566" の例を載せています。この環境では Docker のデーモンが使えないので、moto のサーバーを 127.0.0.1:5000 に立てて同じコードを向けました。
import os, boto3, json, time
from botocore.exceptions import ClientError
ENDPOINT = os.environ.get("ENDPOINT", "http://127.0.0.1:5000") # LocalStack なら http://localhost:4566
def client(name):
return boto3.client(name, endpoint_url=ENDPOINT, region_name="us-east-1",
aws_access_key_id="test", aws_secret_access_key="test")
s3 = client("s3")
s3.create_bucket(Bucket="t666-demo")
s3.put_object(Bucket="t666-demo", Key="hello.txt", Body=b"hello localstack-style test\n")
print("buckets:", [b["Name"] for b in s3.list_buckets()["Buckets"]])
obj = s3.get_object(Bucket="t666-demo", Key="hello.txt")
print("get_object:", obj["Body"].read().decode().strip(), "| ETag", obj["ETag"])
url = s3.generate_presigned_url("get_object",
Params={"Bucket": "t666-demo", "Key": "hello.txt"}, ExpiresIn=60)
print("presigned:", url.split("?")[0])
try:
s3.get_object(Bucket="t666-demo", Key="nai.txt")
except ClientError as e:
print("ClientError:", e.response["Error"]["Code"], "|", str(e))
sqs = client("sqs")
q = sqs.create_queue(QueueName="t666-queue", Attributes={"VisibilityTimeout": "2"})["QueueUrl"]
print("QueueUrl:", q)
sqs.send_message(QueueUrl=q, MessageBody=json.dumps({"order": 1}))
m = sqs.receive_message(QueueUrl=q, MaxNumberOfMessages=1, WaitTimeSeconds=1)["Messages"][0]
print("received:", m["Body"])
print("2回目(直後):", len(sqs.receive_message(QueueUrl=q, WaitTimeSeconds=0).get("Messages", [])))
time.sleep(2.5)
m2 = sqs.receive_message(QueueUrl=q, WaitTimeSeconds=0).get("Messages", [])
print("3回目(2.5秒後):", len(m2))
sqs.delete_message(QueueUrl=q, ReceiptHandle=m2[0]["ReceiptHandle"])
print("delete後:", len(sqs.receive_message(QueueUrl=q, WaitTimeSeconds=0).get("Messages", [])))
print("sts:", client("sts").get_caller_identity()["Arn"])
buckets: ['t666-demo']
get_object: hello localstack-style test | ETag "987aa961d16e35b974c5375aec48f3bb"
presigned: http://127.0.0.1:5000/t666-demo/hello.txt
ClientError: NoSuchKey | An error occurred (NoSuchKey) when calling the GetObject operation: The specified key does not exist.
QueueUrl: http://127.0.0.1:5000/123456789012/t666-queue
received: {"order": 1}
2回目(直後): 0
3回目(2.5秒後): 1
delete後: 0
sts: arn:aws:sts::123456789012:user/moto
出力から分かることを整理します。
- S3:作成・保存・取得・署名付き URL の発行まで、本物向けと同じコードで動きました。存在しないキーは本物と同じ
NoSuchKeyです。接続先が IP アドレスなので URL はパス形式です。 - SQS:可視性タイムアウトを2秒にすると、受け取った直後の2回目は0件、2.5秒後の3回目は同じメッセージがまた見え、削除したあとは0件でした。本物の SQS と同じ「削除するまでは消えない」動きをテストで確かめられます。
- アカウント ID:moto は
123456789012を返しました。LocalStack は、testのようなアクセスキーなら000000000000を使うと公式ページに書かれています。
boto3 の S3 の操作は関連記事「boto3でS3を操作する方法|アップロード・ダウンロード・一覧取得」、SQS の可視性タイムアウトと FIFO は関連記事「Amazon SQSの使い方|送受信・削除と可視性タイムアウト、FIFO」で扱っています。
AWS_ENDPOINT_URLで接続先を切り替える:効く場合と効かない場合
この節では、コードを書き換えずに環境変数で接続先を変える方法と、手元で見つかった落とし穴が分かります。
今の SDK と CLI は、環境変数 AWS_ENDPOINT_URL(全サービス)と AWS_ENDPOINT_URL_<サービス名>(サービスごと)で接続先を変えられます。 LocalStack の boto3 のページも moto のサーバーモードのページも、この環境変数を案内しています。boto3 1.44.5 で確かめた結果が次です。
--- AWS_ENDPOINT_URL=http://127.0.0.1:5000 だけを設定
s3 http://127.0.0.1:5000
sqs http://127.0.0.1:5000
['http://127.0.0.1:5000/123456789012/t666-queue']
--- AWS_ENDPOINT_URL_SQS=http://127.0.0.1:5000 だけを設定
sqs http://127.0.0.1:5000
s3 https://s3.amazonaws.com
2つ目の結果では、S3 の接続先が本物の s3.amazonaws.com のままです。エミュレーターに向けたつもりで一部だけ本物に向く、という事故が起こりうるので、テストでは AWS_ENDPOINT_URL をまとめて設定する方が安全です。
AWS CLI v1 の sqs は AWS_ENDPOINT_URL を使わなかった
AWS CLI 1.46.3(v1)で AWS_ENDPOINT_URL=http://127.0.0.1:5000 を設定して試すと、aws s3 ls は手元に向きましたが、aws sqs list-queues は本物の SQS のエンドポイントに向かいました。--debug の出力の該当行です(手元では 127.0.0.1 以外への接続を止める仕掛けを入れ、外には送っていません)。
botocore.hooks - DEBUG - Event before-building-argument-table-parser.sqs.list-queues: calling handler <function update_endpoint_url at 0x7f681e0a9260>
botocore.regions - DEBUG - Calling endpoint provider with parameters: {'Region': 'us-east-1', 'UseDualStack': False, 'UseFIPS': False, 'Endpoint': 'https://queue.amazonaws.com'}
botocore.regions - DEBUG - Endpoint provider result: https://queue.amazonaws.com
CLI v1 の sqs には接続先を独自に決める処理(update_endpoint_url)があり、それが環境変数より先に効いていました。--endpoint-url を付けたとき、または awslocal を通したときは手元に向きました。CLI v1 で SQS を手元に向けるときは、環境変数だけに頼らず --endpoint-url を明示します。 この挙動はこの版で確かめたもので、CLI v2 では確かめていません。
サービスごとの変数だけで切り替える
AWS_ENDPOINT_URL_SQS だけを設定し、S3 は本物のまま気づかないAWS_ENDPOINT_URL で全サービスをまとめて手元に向ける見分ける問い:「このテストで使うサービスはすべて手元に向いているか」
テストに本物の認証情報を残す
~/.aws の本物の鍵が残ったままテストを流すtest を入れ、設定ファイルの参照先も空のファイルに向ける見分ける問い:「接続先を間違えたとき、本物に届く鍵があるか」
boto3 が認証情報を探す順番は、関連記事「boto3 client・resource・sessionの違いと認証の優先順位」で扱っています。
LocalStackに向けるときに変わる点(motoのサーバーとの違い)
この節では、moto のサーバーで動いたコードを LocalStack に向けるときに、何を変えればよいかが分かります。
コードで変わるのは、ほぼ接続先の URL だけです。 ただし、返ってくる値や確かめ方が少しずつ違います。LocalStack の側は公式ドキュメントの記載、moto の側はこの環境で実際に出た値です。
| 項目 | moto のサーバー(手元で実行) | LocalStack(公式の記載) |
|---|---|---|
| 接続先 | http://127.0.0.1:5000(既定のポートは5000) | http://localhost:4566 または http://localhost.localstack.cloud:4566 |
| 起動 | pip install moto[server] のあと moto_server | lstk start か Docker のイメージ。Docker が前提 |
| 認証トークン | 不要 | 必要(LOCALSTACK_AUTH_TOKEN) |
| アカウント ID | 123456789012 | 既定は 000000000000。12桁の数字のアクセスキーはそのまま ID になる |
| SQS のキューの URL | http://127.0.0.1:5000/123456789012/t666-queue | sqs.<リージョン>.localhost.localstack.cloud:4566/<アカウントID>/<キュー名> の形(表の下の例) |
| S3 の URL の形 | パス形式(/t666-demo/hello.txt) | 推奨は バケット名.s3.localhost.localstack.cloud:4566。パス形式も使える |
| 状態の確認 | /moto-api/(ダッシュボード)、/moto-api/reset で全消去 | /_localstack/health・/_localstack/info、lstk reset |
LocalStack の SQS のページに載っているキューの URL の例は次のとおりです。
http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue
LocalStack の S3 のページによると、仮想ホスト形式でバケット名を正しく読み取るには、ホスト名が s3. で始まる必要があります。また、署名付き URL の署名と期限は既定では確かめないと書かれています。署名付き URL の期限切れのテストは、既定の LocalStack では本物と同じ結果にならないので、設定を変えるか本物の検証用の環境で確かめます。
moto のサーバーモードの公式ページは、例を localhost で書き、127.0.0.1 では動かないことがあると注意しています(この環境の S3 と SQS は 127.0.0.1 で動きました)。
LocalStackとmotoの違い(比較表)とAWS Emulator
この節では、AWS を手元で再現するときによく比べられる LocalStack・moto・AWS Emulator の違いが、事実の表で分かります。
moto は Python のテストの中で AWS の呼び出しを置き換えるライブラリで、サーバーとしても起動できます。LocalStack は Docker で動く別の製品で、多くのサービスを1つのゲートウェイで扱います。 2026年11月11日には、AWS も手元で動く「AWS Emulator」を公開しました(AWS News Blog)。優劣ではなく、動かし方と使い方の違いを並べます。
| 比べる点 | LocalStack | moto | AWS Emulator |
|---|---|---|---|
| 提供元 | LocalStack 社 | オープンソースのプロジェクト(Apache-2.0) | AWS |
| 動かし方 | Docker のコンテナ(lstk・Docker・Helm) | Python の中(@mock_aws)か moto_server | Linux は RPM・Debian のパッケージ。macOS・Windows は Docker イメージを自分で作る |
| 接続先 | localhost:4566 | Python の中なら不要。サーバーは5000 | HTTPS の 127.0.0.1:9297 |
| 料金・アカウント | 無料の Hobby(非商用)と有料プラン。アカウントと認証トークンが要る | 無料。アカウント不要 | 無料(追加のサービス料金なし) |
| 向く使い方 | 複数のサービスをつないだ結合テスト、IaC のデプロイの確認 | Python の単体テストを速く回す | AWS CLI・SDK からの手元のテスト(公式の説明の範囲) |
moto の状態と速さを手元で測りました。1KB のオブジェクトを200回保存する処理を、Python の中で置き換える方法(@mock_aws)とサーバーモードで3回ずつ動かした結果です。
in [1.95, 1.88, 2.24] median ms/req 1.95
srv [6.41, 6.02, 6.15] median ms/req 6.15
server keys after 3 runs: 200
サーバーモードは、テストが終わっても状態が残ります(3回動かしたあともキーは200件)。テストの前に /moto-api/reset や lstk reset で消す手順を決めておきます。AWS Emulator は測っていません。
モック・スタブ・フェイクの言葉の違いは、関連記事「テストダブルとは|スタブ・モック・スパイ・フェイクの違いと使い分け」で扱っています。エミュレーターは、この分け方では「フェイク」(本物に近い動きをする置き換え)にあたります。
テストでの使いどころ(pytestで同じテストを2通りに動かす)
この節では、エミュレーターをテストに組み込む形と、同じテストを接続先だけ変えて動かす例が分かります。
アプリのコードには endpoint_url を書かず、テストのときだけ環境変数で接続先を渡す形にすると、本番・moto・LocalStack を同じコードで切り替えられます。 次のコードは、レポートを S3 に保存して SQS に通知する関数と、そのテストです。
# app.py
import os, json, boto3
def make_client(service):
# 本番では endpoint_url を渡さない。テストのときだけ環境変数で手元に向ける
return boto3.client(service, endpoint_url=os.environ.get("TEST_ENDPOINT") or None)
def save_report(bucket, key, text, queue_url):
make_client("s3").put_object(Bucket=bucket, Key=key, Body=text.encode())
make_client("sqs").send_message(QueueUrl=queue_url,
MessageBody=json.dumps({"bucket": bucket, "key": key}))
return key
# test_app.py(抜粋)
@pytest.mark.skipif(bool(os.environ.get("TEST_ENDPOINT")), reason="server mode")
@mock_aws
def test_in_process():
q = _setup(); app.save_report("t666-reports", "r1.txt", "ok", q); _check(q)
@pytest.mark.skipif(not os.environ.get("TEST_ENDPOINT"), reason="needs endpoint")
def test_against_server():
q = _setup(); app.save_report("t666-reports", "r1.txt", "ok", q); _check(q)
$ pytest -q test_app.py
.s [100%]
1 passed, 1 skipped in 0.55s
$ TEST_ENDPOINT=http://127.0.0.1:5000 pytest -q test_app.py
s. [100%]
1 passed, 1 skipped in 0.40s
LocalStack に向けるときは TEST_ENDPOINT=http://localhost:4566 にします。テストを流す前の確かめ方をまとめると次のとおりです。
- 1本物の認証情報を外したかダミーの test を入れ、~/.aws を読ませない
- 2すべてのクライアントが手元に向いているかclient.meta.endpoint_url を表示して確かめる
- 3リージョンを決めたか無いと NoRegionError。us-east-1 にそろえる
- 4テストの前に状態を消すかサーバー型は前回のデータが残る
- 5エミュレーターで確かめられない点を分けたかIAM の権限・名前の決まり・上限は本物の検証用環境で
pytest の fixture とモックの基本は、関連記事「pytest 使い方|導入からfixture・mock・カバレッジまで実行結果つき」で扱っています。
LocalStackでよくあるエラー/つまずき(症状表)
この節では、LocalStack や moto に向けたときによく出るエラーの原文と、原因・直し方が分かります。
原文の多くは手元の moto のサーバーに向けて出したもので、認証トークンの行は公式ページの記載です。
| 表示(原文) | 原因 | 直し方 |
|---|---|---|
Could not connect to the endpoint URL: "http://127.0.0.1:4566/"(EndpointConnectionError) | エミュレーターが起動していない・ポートが違う | lstk status や /_localstack/health で起動を確かめ、ポートを合わせる |
Unable to locate credentials(NoCredentialsError) | エミュレーター相手でも認証情報が要る | AWS_ACCESS_KEY_ID=test などダミーを入れる |
You must specify a region.(NoRegionError) | リージョンが決まっていない | region_name="us-east-1" か AWS_DEFAULT_REGION |
IllegalLocationConstraintException(The unspecified location constraint is incompatible…) | us-east-1 以外で LocationConstraint を付けずにバケットを作った | CreateBucketConfiguration={"LocationConstraint": "ap-northeast-1"} を付ける |
AWS.SimpleQueueService.NonExistentQueue(The specified queue does not exist.) | キューが無い・リージョンが違う | 作成したリージョンと同じリージョンで呼ぶ。別のリージョンの一覧は空だった |
License activation failed! | 認証トークンが無い・無効・期限切れ | LOCALSTACK_AUTH_TOKEN を確かめ、/_localstack/info を見る |
手元に向けたはずが本物の URL(https://queue.amazonaws.com など)になる | サービスごとの変数だけ設定した・CLI v1 の sqs が環境変数を使わない | AWS_ENDPOINT_URL でまとめて設定し、CLI v1 は --endpoint-url を付ける |
WARNING: 'awslocal' is deprecated. | awslocal は非推奨 | lstk aws に移る。急がないときはそのまま動く |
エミュレーターでは通るが本物では断られる例
大文字とアンダースコアを含む T666_Bad という名前でバケットを作ると、moto のサーバーではそのまま作れました。
7 バケット名の大文字 OK {... 'HTTPStatusCode': 200, ... 'Location': '/T666_Bad'}
本物の S3 の汎用バケットの名前は、小文字・数字・ピリオド・ハイフンだけと決まっています(Amazon S3 ユーザーガイドのバケットの名前の決まり)。エミュレーターで通ったことは、本物で通ることの証明になりません。 名前の決まり・IAM の権限・上限(クォータ)・遅延は、本物の検証用の環境で確かめます。
LocalStackを使うかどうかの判断表
この節では、手元で AWS を再現するときに、LocalStack・moto・本物の検証用アカウントのどれを選ぶかの目安が分かります。
「何を確かめたいか」と「どこで動かすか」で選びます。 提供元の利用条件(Hobby は非商用)も、選ぶときの条件に入ります。
| 確かめたいこと・状況 | 向く選択 | 理由 |
|---|---|---|
| Python の関数の単体テストを速く回したい | moto(@mock_aws) | Docker もネットワークも要らず、1回2ms ほどで動いた |
| Python 以外の言語や AWS CLI から試したい | moto のサーバー・LocalStack・AWS Emulator | 接続先の URL を変えれば、どの SDK からも呼べる |
| S3→Lambda→SQS のように複数をつないで動かしたい | LocalStack | 1つのゲートウェイで多くのサービスを扱い、Lambda をコンテナで動かせる |
| Terraform・CDK のデプロイを手元で試したい | LocalStack | 公式に Terraform・CDK・SAM との連携がある |
| Docker が使えない環境で動かしたい | moto | pip だけで動く |
| IAM の権限・上限・料金・本番と同じ遅延を確かめたい | 本物の検証用アカウント | エミュレーターでは同じにならない部分がある |
| 会社の仕事で LocalStack を使いたい | 有料プランを検討 | 提供元の説明では Hobby は非商用向け。最新の利用条件を確かめる |
迷ったときは、次の順に段階を上げると、費用と手間を小さく保てます。
- 1単体テスト → moto で Python の中だけで置き換える速い。ネットワークも Docker も使わない
- 2CLI や他の言語から → エミュレーターのサーバーに URL を向けるmoto のサーバー・LocalStack・AWS Emulator
- 3複数のサービスをつなぐ・IaC を試す → LocalStackプランと利用条件を先に確かめる
- 4本番に出す前 → 本物の検証用アカウントで確かめる権限・名前の決まり・上限・料金を最後に確かめる
よくある質問
この節では、LocalStack についてよく聞かれる疑問への短い答えが分かります。
Q. LocalStack は無料で使えますか。
無料の Hobby プランがあります。ただし、提供元の説明では趣味など非商用の利用向けで、アカウントの作成と認証トークンが要ります。仕事で使う場合は、Base(年払いで1ライセンス月39 USD)以上を料金ページが案内しています(2026年11月18日時点)。
Q. 以前のようにアカウントなしで LocalStack を動かせますか。
公式ブログによると、2026年3月の変更より前の版のタグは、認証なしで手元でも CI でも動かせます。ただし、その版には更新や安全面の修正が届きません。
Q. LocalStack の読み方は何ですか。
英語の local(手元の)と stack(ソフトウェアの積み重ね)をつなげた名前で、カタカナでは「ローカルスタック」と書かれます。
Q. LocalStack で使うアクセスキーは何にすればよいですか。test のようなダミーの値を使います。公式ページによると、AKIA・ASIA で始まる本物の形のキーは既定では受け付けず、アカウント ID は 000000000000 になります。本物の鍵は使いません。
Q. awslocal と lstk aws の違いは何ですか。
どちらも aws コマンドに LocalStack の接続先を付けるラッパーです。awslocal は pip で入る Python 製で、今は非推奨です。lstk aws は新しい CLI の lstk の機能で、公式はこちらを勧めています。
Q. LocalStack のポート 4566 以外の 4510〜4559 は何に使いますか。
公式の「External Service Port Range」のページによると、サービスが外部のプログラムを起動するとき、この範囲から空いているポートを自動で選びます。OpenSearch などにゲートウェイを通さず直接つなぐときに使われます。
Q. Windows や Mac でも LocalStack は動きますか。
Docker が動けば使えます。lstk には Linux・macOS・Windows 向けのバイナリがあり、GUI の LocalStack Desktop もあります(この記事では動かしていません)。
Q. LocalStack で作ったデータは再起動すると消えますか。
料金ページによると、無料の Hobby には状態の保存(永続化)が無く、Base 以上で状態の保存と Cloud Pods が使えます。
Q. エミュレーターでテストが通れば本番でも動きますか。
保証されません。手元では、本物では作れない名前のバケットがエミュレーターでは作れました。権限・名前の決まり・上限は、本物の検証用の環境でも確かめます。
まとめ
- LocalStack は、S3・SQS・Lambda などの AWS のサービスを手元の Docker で再現するエミュレーター。コードの接続先を
localhost:4566に向けて使う。 - 2026年3月23日から1つのイメージにまとまり、無料の Hobby も含めてアカウントと認証トークン(
LOCALSTACK_AUTH_TOKEN)が必要。Hobby は提供元の説明では非商用向けで、Base は年払いで月39 USD、Ultimate は月89 USD(2026年11月18日時点)。 - インストールは新しい CLI の lstk(推奨)か Docker のイメージ。以前の
localstackCLI と awslocal は非推奨で、後継はlstk startとlstk aws。 - boto3 は
endpoint_urlかAWS_ENDPOINT_URLで切り替わる。手元では S3・SQS が本物向けと同じコードで動いた一方、サービスごとの変数や CLI v1 の sqs では本物の URL に向く場合があった。 - moto は Python の中で速く(1回約2ms)、LocalStack は複数のサービスや IaC に向く。エミュレーターで通らない・本物と違う部分は、最後に本物の検証用の環境で確かめる。
参考・出典
確認日はいずれも 2026年11月18日です。
- LocalStack「Installation」:https://docs.localstack.cloud/aws/getting-started/installation/
- LocalStack「Auth Token」:https://docs.localstack.cloud/aws/getting-started/auth-token/
- LocalStack「lstk」:https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/
- LocalStack「lstk Migration Guide」:https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/migration/
- LocalStack「AWS CLI」:https://docs.localstack.cloud/aws/integrations/aws-native-tools/aws-cli/
- LocalStack「Deprecated Wrapper Scripts」:https://docs.localstack.cloud/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts/
- LocalStack「Python (Boto3)」:https://docs.localstack.cloud/aws/integrations/aws-sdks/python-boto3/
- LocalStack「AWS Services」:https://docs.localstack.cloud/aws/services/
- LocalStack「Simple Queue Service (SQS)」:https://docs.localstack.cloud/aws/services/sqs/
- LocalStack「Simple Storage Service (S3)」:https://docs.localstack.cloud/aws/services/s3/
- LocalStack「Credentials」:https://docs.localstack.cloud/references/credentials/
- LocalStack「Multi-account setups」:https://docs.localstack.cloud/aws/capabilities/config/multi-account-setups/
- LocalStack「Pricing」:https://www.localstack.cloud/pricing
- LocalStack Blog「Important Updates to Pricing & Packaging for LocalStack for AWS」:https://blog.localstack.cloud/2026-upcoming-pricing-changes/
- LocalStack Blog「The Road Ahead for LocalStack」:https://blog.localstack.cloud/the-road-ahead-for-localstack/
- Moto「Getting Started with Moto」:https://docs.getmoto.org/en/latest/docs/getting_started.html
- Moto「Non-Python SDK’s / Server Mode」:https://docs.getmoto.org/en/latest/docs/server_mode.html
- AWS News Blog「Test your applications against AWS locally with AWS Emulator」:https://aws.amazon.com/blogs/aws/test-your-applications-against-aws-locally-with-aws-emulator/
- AWS「General purpose bucket naming rules」(Amazon S3 ユーザーガイド):https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html
- LocalStack「External Service Port Range」:https://docs.localstack.cloud/references/external-ports/
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「LocalStackとは|AWSを手元で再現する使い方・料金・対応サービス」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。