boto3の使い方入門【Python×AWS】認証設定からS3操作・ページネーション・エラー処理まで

2026年7月 全面改稿: 本記事は2022年に「boto3のセットアップとS3・AIサービスの利用例」を解説した記事だったが、認証周りの推奨手順やAPIの位置づけが当時から変わっている。2026年7月時点の一次情報( boto3公式ドキュメント )に基づき、内容を全面的に書き直した。

boto3 は、PythonからAWSの各サービスを操作するための公式SDKである。S3にファイルを置く、DynamoDBにレコードを書き込む、Lambda関数を呼び出す——こうした操作をPythonのコードから直接実行できるようにするライブラリで、AWS CLIの内部でも同じ基盤(botocore)が使われている。

本記事では、boto3のインストールと認証設定から、低レベルAPIである client と高レベルAPIである resource の違いと現状、S3操作の基本、paginatorによる大量データの扱い、エラー処理とリトライ設定、そしてS3以外の主要サービスの呼び出し方までを、2026年7月時点の公式ドキュメントに基づいて順に解説する。

1. boto3とは

boto3は、Amazon Web Services(AWS)が開発・保守するPython向けの公式SDKである。名前の「boto」はカワイルカ(Amazon river dolphin)に由来し、「3」はPython 3世代を指す。内部的には、AWSの各サービスAPIをHTTPリクエストとして実際に送受信する低レベルライブラリ botocore の上に構築されている。AWS CLI(aws コマンド)もこのbotocoreを共有しており、boto3とAWS CLIは認証情報の設定ファイルも共通で読み込む。

boto3を使うと、次のようなことがPythonコードから行える。

• S3へのファイルのアップロード/ダウンロード、バケット一覧の取得、presigned URLの発行
• DynamoDBへのアイテムの読み書き、クエリの実行
• Lambda関数の呼び出し(同期・非同期)
• EC2インスタンスの起動・停止、SQSキューへのメッセージ送受信、Translate・Comprehendなどのマネージド機械学習サービスの呼び出し

対応サービスはAWSが提供するほぼ全サービスに及び、新サービスがリリースされると通常は同時期にboto3側の対応もリリースされる。本記事執筆時点(2026年7月)の最新バージョンは 1.43.51(2026年7月17日リリース)で、対応する最小Pythonバージョンは Python 3.10以上 である。

2. インストールと認証設定

インストール

boto3はPyPIで配布されている通常のパッケージなので、pip あるいは uv で導入できる。

# pip の場合
pip install boto3

# uv でプロジェクトに追加する場合
uv add boto3

Python自体の環境構築(バージョン管理・仮想環境・依存関係の再現)を体系的に整えたい場合は、 Python環境構築の決定版 で2026年時点のベストプラクティス(uvを中心とした構成)をまとめているので、そちらも参照してほしい。

認証情報の設定方法と優先順位

boto3はAWSサービスを呼び出す際、必ずAWS側で身元を証明する「認証情報(credentials)」が必要になる。boto3自身はどこにも認証情報を保存しておらず、コード実行時に複数の場所を順番に探索し、最初に見つかった認証情報を採用する。この探索順序は次の通りである(上から順に評価し、見つかった時点でそこで確定する)。

1. boto3.client() / boto3.Session() の引数として直接渡された認証情報
2. 環境変数(AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN)
3. AssumeRoleプロバイダー(~/.aws/config の role_arn + source_profile)
4. Web IDフェデレーションプロバイダー(OIDC連携)
5. IAM Identity Center(旧AWS SSO)認証情報プロバイダー
6. 共有credentialsファイル(~/.aws/credentials)
7. コンソールログイン認証情報
8. AWS configファイル(~/.aws/config)
9. Boto2互換の設定ファイル(/etc/boto.cfg、~/.boto)
10. コンテナ認証情報プロバイダー(ECSタスクロールなど)
11. EC2インスタンスメタデータサービス(インスタンスに設定されたIAMロール)

図にすると次のような流れになる。

図1: boto3が認証情報を解決する優先順位

IAM Identity Center(SSO)を使う — 2026年の推奨

長期間有効なアクセスキーID・シークレットアクセスキーを発行して ~/.aws/credentials に直書きする方法は、2022年当時の本記事でも紹介していたが、キーが漏洩した場合に無期限で悪用されるリスクが常につきまとう。2026年現在の公式ドキュメントでは、個人の対話的な利用については IAM Identity Center(組織のユーザーをAWSアカウント群に対してシングルサインオンで割り当てる仕組み、旧称AWS SSO)を使い、一時的な認証情報を都度取得する方式が推奨されている。

# 初回のみ: SSOプロファイルを対話形式で作成(~/.aws/config に書き込まれる)
aws configure sso

# セッションが切れたら再ログイン(有効期限内はSDK側が自動でトークンをリフレッシュ)
aws sso login --profile my-sso-profile

作成したプロファイルは、boto3から次のように指定するだけで利用できる。

import boto3

session = boto3.Session(profile_name="my-sso-profile")
s3 = session.client("s3")

一方で、CI/CDパイプラインやEC2/ECS上で動くアプリケーションのように「対話的なログインができない」実行環境では、IAMロール(EC2インスタンスプロファイルやECSタスクロールなど)を使うのが基本である。これらは認証情報の探索順序の末尾(表の10・11)で自動的に拾われるため、コード側で明示的に何かを指定する必要がない。

アクセスキーを使わざるを得ない場合でも、コードにハードコーディングしてはならない。環境変数か ~/.aws/credentials に置き、リポジトリには含めないようにする。

# 環境変数での指定(一時的な検証用途など)
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="ap-northeast-1"

3. clientとresourceの違いと現状

boto3には、AWSサービスを呼び出すためのインターフェースが2種類ある。

• client(低レベルAPI): 各サービスのAPIオペレーションと1対1に対応する薄いラッパー。メソッド名はAPI名をsnake_caseにしたもので、レスポンスは素朴なPythonの辞書として返る。
• resource(高レベルAPI): バケットやテーブルなどを「オブジェクト」として扱えるようにした、よりPythonらしい抽象化レイヤー。属性の遅延ロードやコレクション操作など、便利な機能を備える。

import boto3

# client: 低レベルAPI
s3_client = boto3.client("s3")
s3_client.list_buckets()

# resource: 高レベルAPI
s3_resource = boto3.resource("s3")
for bucket in s3_resource.buckets.all():
    print(bucket.name)

2022年時点では「シンプルに書きたいならresource、細かく制御したいならclient」という使い分けが一般的な説明だったが、この状況は変わっている。boto3の開発チームは、resourceインターフェースへの新機能追加を行わない方針を明言しており、GitHub上の公式な説明では次のように述べられている。

The AWS Python SDK team does not intend to add new features to the resources interface in boto3. Existing interfaces will continue to operate during boto3’s lifecycle. Customers can find access to newer service features through the client interface. (boto3開発チームは、resourcesインターフェースに新機能を追加する予定はない。既存のインターフェースはboto3のライフサイクルを通じて動作し続けるが、新しいサービス機能へのアクセスはclientインターフェースを通じて提供される。)

これは「非推奨(deprecated)」ではなく、既存のresourceコードが動かなくなるわけではない。ただし、AWSの新サービスや既存サービスの新機能は基本的にclient側にしか追加されない「機能凍結(feature freeze)」状態にあり、DynamoDBなど一部のサービスドキュメントでは明示的にclientの利用が案内されている。そのため、2026年時点で新規に書くコードはclientを基本線とするのが妥当である。既存プロジェクトで既にresourceベースのコードが動いている場合、無理に書き換える必要はないが、新しく追加する処理はclientで書くのがよい。

本記事の以降のサンプルコードもすべてclient APIで統一する。

4. S3操作の基本

S3(Simple Storage Service)は、boto3で最もよく使われるサービスの一つである。ここではバケット一覧の取得、ファイルのアップロード/ダウンロード、presigned URLの発行という基本操作を扱う。

クライアントの初期化とバケット一覧

import boto3

s3 = boto3.client("s3", region_name="ap-northeast-1")

response = s3.list_buckets()
for bucket in response["Buckets"]:
    print(bucket["Name"])

ファイルのアップロード/ダウンロード

ローカルファイルをアップロードするには upload_file、ダウンロードするには download_file を使う。内部的にはマルチパートアップロード/ダウンロードが必要な大きなファイルも自動的に分割して並列転送してくれる。

import boto3
from botocore.exceptions import ClientError

s3 = boto3.client("s3", region_name="ap-northeast-1")

# アップロード
try:
    s3.upload_file("local_file.csv", "my-bucket", "data/local_file.csv")
except ClientError as e:
    print(f"アップロードに失敗しました: {e}")

# ダウンロード
try:
    s3.download_file("my-bucket", "data/local_file.csv", "downloaded.csv")
except ClientError as e:
    print(f"ダウンロードに失敗しました: {e}")

ファイルパスではなくファイルライクオブジェクト(すでにメモリ上に読み込んだデータなど)を直接扱いたい場合は、upload_fileobj / download_fileobj を使う。バイナリモード("rb" / "wb")で開く点に注意する。

with open("local_file.csv", "rb") as f:
    s3.upload_fileobj(f, "my-bucket", "data/local_file.csv")

メタデータやACLなどの追加オプションは ExtraArgs にまとめて渡す。

s3.upload_file(
    "local_file.csv",
    "my-bucket",
    "data/local_file.csv",
    ExtraArgs={"Metadata": {"source": "batch-job"}},
)

presigned URLの発行

presigned URL(署名付きURL)は、IAM認証情報を持たない第三者に対して、期限付きで特定のS3オブジェクトへのアクセスを許可する仕組みである。フロントエンドから直接S3にファイルをアップロードさせたり、一時的にファイルを共有したりする用途で使う。

import boto3
from botocore.exceptions import ClientError

s3 = boto3.client("s3", region_name="ap-northeast-1")

try:
    url = s3.generate_presigned_url(
        "get_object",
        Params={"Bucket": "my-bucket", "Key": "data/local_file.csv"},
        ExpiresIn=3600,  # 有効期限(秒)。既定値も3600秒
    )
    print(url)
except ClientError as e:
    print(f"presigned URLの生成に失敗しました: {e}")

generate_presigned_url の第1引数には、対象操作のAPI名(取得なら get_object、アップロード用のURLを発行したい場合は put_object)を渡す。生成されるのはあくまでURL文字列であり、実際にAWSへリクエストが飛ぶわけではないため、この呼び出し自体に通信コストはかからない。

5. 大量データの扱い — paginator と waiter

paginator によるページネーション

S3の list_objects_v2 やDynamoDBの query など、多くのAWS APIは1回のリクエストで返せる件数に上限があり、続きを取得するには「次のページのトークン」を使って繰り返しリクエストする必要がある。この定型処理を自動化してくれるのが paginator である。

import boto3

s3 = boto3.client("s3", region_name="ap-northeast-1")
paginator = s3.get_paginator("list_objects_v2")

page_iterator = paginator.paginate(Bucket="my-bucket", Prefix="logs/")

for page in page_iterator:
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])

get_paginator() に渡すオペレーション名の一覧は、対象のclientが持つメソッドのうちページネーション対応のものに限られる。すべてのAPIオペレーションにpaginatorが用意されているわけではない点に注意する。PaginationConfig を使えば、取得件数の上限やページサイズも制御できる。

page_iterator = paginator.paginate(
    Bucket="my-bucket",
    PaginationConfig={"MaxItems": 1000, "PageSize": 100},
)

さらに、JMESPathによるクライアント側フィルタリングを search() で連結することもできる。

filtered = page_iterator.search("Contents[?Size > `1000000`][]")
for obj in filtered:
    print(obj["Key"])

waiter — 状態変化を待つ

waiterは、リソースが特定の状態になるまでポーリングして待機する仕組みである。たとえば、バケット作成直後にオブジェクトが実際に読み取り可能になるまで待ちたい場合などに使う。

s3 = boto3.client("s3", region_name="ap-northeast-1")

# バケットが存在する状態になるまで待機
waiter = s3.get_waiter("bucket_exists")
waiter.wait(Bucket="my-bucket")

# 特定のオブジェクトが存在する状態になるまで待機
obj_waiter = s3.get_waiter("object_exists")
obj_waiter.wait(Bucket="my-bucket", Key="data/local_file.csv")

利用可能なwaiterの一覧は、client.waiter_names で確認できる。サービスによってはwaiterが1つも定義されていない場合もある。

6. エラー処理とリトライ

ClientError の構造

boto3経由でAWS側からエラーレスポンスが返ってきた場合、共通して botocore.exceptions.ClientError 例外が送出される。エラーの詳細は response["Error"]["Code"] と response["Error"]["Message"] に入っている。

import boto3
from botocore.exceptions import ClientError, NoCredentialsError

s3 = boto3.client("s3", region_name="ap-northeast-1")

try:
    s3.head_object(Bucket="my-bucket", Key="not-exist.csv")
except ClientError as e:
    code = e.response["Error"]["Code"]
    if code == "404":
        print("オブジェクトが存在しません")
    else:
        raise
except NoCredentialsError:
    print("認証情報が見つかりません。aws configure sso や aws sso login を確認してください")

各client オブジェクトは client.exceptions からサービス固有の例外クラスにもアクセスできる。エラーコードの文字列比較よりも型で分岐したい場合に有用である。

try:
    dynamodb.describe_table(TableName="not-exist-table")
except dynamodb.exceptions.ResourceNotFoundException:
    print("テーブルが存在しません")

リトライ設定(botocore.config.Config)

スロットリング(レート制限)などの一時的なエラーに対しては、botocoreが自動的にリトライを行う。既定の挙動を変更したい場合は botocore.config.Config をclient生成時に渡す。

import boto3
from botocore.config import Config

config = Config(
    retries={
        "total_max_attempts": 10,  # 初回リクエストを含めた最大試行回数
        "mode": "standard",        # legacy(既定) / standard / adaptive
    }
)

s3 = boto3.client("s3", region_name="ap-northeast-1", config=config)

mode には3種類ある。既定の legacy は最小限のエラーのみリトライするのに対し、standard はスロットリング系のエラーを幅広くカバーし指数バックオフとサーキットブレーカー的な挙動を備える。adaptive はさらに、クライアント側でリクエストのレートそのものを動的に調整する(実験的機能)。特別な理由がなければ standard を明示的に指定しておくと、挙動の見通しが良くなる。

なお、~/.aws/config にプロファイル単位で同様の設定を書くこともできる。

[profile my-sso-profile]
region = ap-northeast-1
retry_mode = standard
max_attempts = 10

7. S3以外の主要サービス例

boto3の使い方はサービスが変わっても基本的に同じで、boto3.client("サービス名") を作り、対応するメソッドを呼ぶだけである。ここではDynamoDBとLambdaの最小例を示す。

DynamoDB

client APIでDynamoDBを扱う場合、値の型を {"S": "文字列"} {"N": "123"} のように明示的に指定する必要がある(resource APIではこの変換が暗黙的に行われていたが、前述の通り新規開発ではclientが推奨される)。

import boto3

dynamodb = boto3.client("dynamodb", region_name="ap-northeast-1")

# 書き込み
dynamodb.put_item(
    TableName="my-table",
    Item={
        "pk": {"S": "user#1"},
        "name": {"S": "Taro"},
        "age": {"N": "30"},
    },
)

# 読み取り
response = dynamodb.get_item(
    TableName="my-table",
    Key={"pk": {"S": "user#1"}},
)
print(response.get("Item"))

Lambda

Lambda関数を同期呼び出しし、JSONのペイロードをやり取りする例。

import json
import boto3

lambda_client = boto3.client("lambda", region_name="ap-northeast-1")

response = lambda_client.invoke(
    FunctionName="my-function",
    InvocationType="RequestResponse",  # 同期呼び出し(既定)。非同期なら "Event"
    Payload=json.dumps({"key": "value"}),
)

result = json.loads(response["Payload"].read())
print(result)

InvocationType を "Event" にすると、Lambda側にリクエストをキューイングした時点で即座に制御が返る非同期呼び出しになる。同期呼び出しのペイロードは最大6MB、非同期呼び出しは最大1MBという制約がある。

まとめ

boto3は、pip install boto3 あるいは uv add boto3 で導入できるAWSの公式Python SDKである。認証情報は環境変数・共有credentialsファイル・IAM Identity Center(SSO)・IAMロールなど複数の場所から決まった優先順位で解決され、2026年時点では対話的な利用にはIAM Identity Centerを、CI/CDやEC2/ECS上ではIAMロールを使うのが基本線になる。APIインターフェースはclientとresourceの2種類があるが、resourceは新機能が追加されない機能凍結状態にあるため、新規に書くコードはclientを基本にするのが2026年時点の現実的な選択である。

S3操作(アップロード/ダウンロード/presigned URL)、大量データを扱うpaginator、状態変化を待つwaiter、ClientError によるエラー処理とリトライ設定という基本パターンを押さえておけば、DynamoDBやLambdaなど他のサービスにもほぼそのまま応用できる。

よくある質問(FAQ)

boto3とawscliの違いは?

boto3はPythonのコードからAWSサービスを操作するためのSDKライブラリであり、AWS CLI(aws コマンド)はシェルからAWSサービスを操作するためのコマンドラインツールである。両者は内部的に同じ低レベルライブラリ(botocore)を共有しており、認証情報の設定ファイル(~/.aws/credentials、~/.aws/config)も共通で読み込む。シェルスクリプトやワンライナーで完結する操作にはAWS CLI、条件分岐や繰り返し処理を伴うアプリケーションロジックにはboto3が向く(第2章参照)。

アクセスキーを直書きしてはいけない理由は?

アクセスキーID・シークレットアクセスキーはコードやリポジトリに含めると、意図せずGitHubなどに公開されたり、ログに残ったりするリスクが常につきまとう。長期間有効なキーが漏洩すると、無期限に不正利用され得る。boto3は環境変数や ~/.aws/credentials、IAM Identity Centerなど複数の経路から認証情報を自動的に読み込めるため、コードにはどの経路で認証するかだけを書き、実際の値はコード外で管理するのが基本である(第2章参照)。

resourceとclientどちらを使うべき?

2026年時点では、新規に書くコードは基本的に client を使うべきである。boto3開発チームはresourceインターフェースへの新機能追加を行わない方針を明言しており、新しいAPI機能やサービスはclient側にしか実装されない。既存のresourceベースのコードがすぐに動かなくなるわけではないが、今後保守・拡張していくコードはclientで書くのが安全である(第3章参照)。

認証エラー(NoCredentialsError)の対処は?

botocore.exceptions.NoCredentialsError は、boto3が探索順序上のどの場所からも有効な認証情報を見つけられなかった場合に発生する。まずは aws sso login --profile <プロファイル名> でIAM Identity Centerのセッションが有効かを確認し、次に環境変数や ~/.aws/credentials の設定漏れ、プロファイル名の指定間違い(boto3.Session(profile_name=...))がないかを確認する。EC2/ECS上で実行している場合は、インスタンスプロファイルやタスクロールにIAMロールが正しくアタッチされているかを確認する(第2章・第6章参照)。

関連書籍

boto3の背後にあるAWSサービス自体を体系的に押さえたい読者には、図解中心の定番教科書の最新改訂版を挙げておく。

他の分野の定番書は エンジニアにおすすめの技術書10選 にまとめている。

参考文献

• AWS (2026). Boto3 Documentation. https://docs.aws.amazon.com/boto3/latest/guide/
• AWS (2026). Boto3: Credentials. https://docs.aws.amazon.com/boto3/latest/guide/credentials.html
• AWS (2026). Boto3: Clients. https://docs.aws.amazon.com/boto3/latest/guide/clients.html
• AWS (2026). Boto3: Resources. https://docs.aws.amazon.com/boto3/latest/guide/resources.html
• AWS (2026). Boto3: Uploading files. https://docs.aws.amazon.com/boto3/latest/guide/s3-uploading-files.html
• AWS (2026). Boto3: Presigned URLs. https://docs.aws.amazon.com/boto3/latest/guide/s3-presigned-urls.html
• AWS (2026). Boto3: Paginators. https://docs.aws.amazon.com/boto3/latest/guide/paginators.html
• AWS (2026). Boto3: Error handling. https://docs.aws.amazon.com/boto3/latest/guide/error-handling.html
• AWS (2026). Boto3: Retries. https://docs.aws.amazon.com/boto3/latest/guide/retries.html
• AWS (2026). Configuring IAM Identity Center authentication with the AWS CLI. https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html
• boto/boto3 (2024). Explanation of the freeze of resources development (Discussion #4147). https://github.com/boto/boto3/discussions/4147
• PyPI. boto3. https://pypi.org/project/boto3/