結論

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 との違い、症状表と判断表

2026年11月18日更新|LocalStack 公式ドキュメント・料金ページ・公式ブログで確認・moto のサーバーを 127.0.0.1 に立てて boto3 と AWS CLI で S3・SQS を実行

この記事で実際に動かしたもの: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

イメージが1つになった

localstack/localstack と localstack/localstack-pro は同じ中身のイメージになった。

2026年3月から

2

起動に認証トークンが要る

トークンを設定せずに最新版を起動すると、トークンを求められる。CI では CI 用のトークンを使う。

無料の Hobby も同じ

3

GitHub のリポジトリは残る

公開のリポジトリは残り、活動していない(inactive)と明記された。参照用の位置づけになる。

定期的な更新は約束されない

4

以前の版のタグは使える

以前の版のタグは、認証なしで手元でも 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
468USDBase を1人・1年(年払い)月払いだと540 USD
13.3%年払いで下がる割合Base の月払いと比べて
5,340USDUltimate を5人・1年年払いの価格で計算

無料の 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 -dlstk start(または lstk)
localstack wait不要(lstk start が準備できるまで待つ)
localstack stoplstk stop
localstack status dockerlstk status
localstack logs -f -n 100lstk logs --follow --tail 100
localstack state resetlstk 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_serverlstk start か Docker のイメージ。Docker が前提
認証トークン不要必要(LOCALSTACK_AUTH_TOKEN)
アカウント ID123456789012既定は 000000000000。12桁の数字のアクセスキーはそのまま ID になる
SQS のキューの URLhttp://127.0.0.1:5000/123456789012/t666-queuesqs.<リージョン>.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_serverLinux は RPM・Debian のパッケージ。macOS・Windows は Docker イメージを自分で作る
接続先localhost:4566Python の中なら不要。サーバーは5000HTTPS の 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
1.95msPython の中で置き換えput_object 1回あたり(中央値)
6.15msサーバーモード(HTTP 経由)約3.2倍。それでも1秒に約160回
112MBmoto のサーバーのメモリ起動して約4分後の常駐の大きさ(RSS)

サーバーモードは、テストが終わっても状態が残ります(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
IllegalLocation​ConstraintException(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 のように複数をつないで動かしたいLocalStack1つのゲートウェイで多くのサービスを扱い、Lambda をコンテナで動かせる
Terraform・CDK のデプロイを手元で試したいLocalStack公式に Terraform・CDK・SAM との連携がある
Docker が使えない環境で動かしたいmotopip だけで動く
IAM の権限・上限・料金・本番と同じ遅延を確かめたい本物の検証用アカウントエミュレーターでは同じにならない部分がある
会社の仕事で LocalStack を使いたい有料プランを検討提供元の説明では Hobby は非商用向け。最新の利用条件を確かめる

迷ったときは、次の順に段階を上げると、費用と手間を小さく保てます。

  1. 1単体テスト → moto で Python の中だけで置き換える速い。ネットワークも Docker も使わない
  2. 2CLI や他の言語から → エミュレーターのサーバーに URL を向けるmoto のサーバー・LocalStack・AWS Emulator
  3. 3複数のサービスをつなぐ・IaC を試す → LocalStackプランと利用条件を先に確かめる
  4. 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 のイメージ。以前の localstack CLI と 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期連続の黒字決算。

ABOUT RJC RJCがどんな会社か知る 考え方、研修、働き方、福利厚生、社員の前職まで。RJCのことが丸わかり! RJC丸わかりページへ JOB DESCRIPTION 仕事内容・待遇を見てみる 仕事内容、給与・待遇、選考の流れ。経験者も未経験も!応募前に知りたいこと、まとめました! 募集要項を見る ENTRY エントリーする エントリーは1〜2分・履歴書不要です。まずは話を聞いてみたい、という方でも歓迎です! エントリーフォームへ

成長のヒミツ、 ぜんぶ丸わかり