Python *argsと**kwargsの使い方｜可変長引数とデフォルト引数

Pythonの *args は「余った位置引数をタプルにまとめて受け取る」仮引数、**kwargs は「余ったキーワード引数を辞書にまとめて受け取る」仮引数です。 この2つを使うと、引数の個数が決まっていない関数（可変長引数の関数）を書けます。args・kwargs という名前は慣習で、意味を持つのは * と ** の記号です。

この記事では、関数定義で使える引数の5種類（位置専用・通常・*args・キーワード専用・**kwargs）を 並べる順番の図と表で整理し、すべてのコードを Python 3.14.7 で実行した結果と一緒に載せています（3.11.15 でも同じコードを流し、違いがあった箇所は明記しています）。呼び出し側の *リスト・**辞書 によるアンパック、TypeError の代表パターンと直し方、デフォルト引数にリストを置いたときの挙動、型ヒントの書き方、デコレータでの引数転送の定型、functools.partial まで順に見ていきます。

*argsと**kwargsの早見表

引数を並べる順番は次のとおりです。

def f(位置専用, /, 通常, *args, キーワード専用, **kwargs):

*argsの使い方：位置引数をタプルで受け取る

前提：Python 3.8 以降（位置専用引数 / を使う例があるため）。この記事の実行結果は Python 3.14.7 のものです。

def show(*args, **kwargs):
    print("args  =", args, type(args).__name__)
    print("kwargs=", kwargs, type(kwargs).__name__)

show(1, 2, 3, name="pen", price=150)
show()

args  = (1, 2, 3) tuple
kwargs= {'name': 'pen', 'price': 150} dict
args  = () tuple
kwargs= {} dict

*args はタプル、**kwargs は辞書です。 何も渡さなければ空のタプルと空の辞書になるので、None かどうかを調べる必要はありません。

*args だけを使った合計の関数です。名前は args でなくても構いません。中身がわかる名前にすると読みやすくなります。

def total(*prices):
    return sum(prices)

print(total(), total(100), total(100, 200, 300))

0 100 600

**kwargsの使い方：キーワード引数を辞書で受け取る

**kwargs は、仮引数に名前のないキーワード引数をまとめて辞書にします。HTML タグの属性のように、どんな名前が来るか事前に決められないときに向いています。

def make_tag(name, **attrs):
    text = "".join(f' {k}="{v}"' for k, v in attrs.items())
    return f"<{name}{text}>"

print(make_tag("a", href="/items", target="_blank"))

<a href="/items" target="_blank">

辞書なので、attrs.get("href")、"target" in attrs、attrs.items() といった辞書の操作がそのまま使えます。渡した順番も保たれます。

引数5種類の順番（図と表）

Python の関数定義では、引数を5つの種類に分けられます。並べる順番は決まっていて、入れ替えると SyntaxError になります。

flowchart LR
    A["1. 位置専用<br>a, b"] --> S1["/"]
    S1 --> B["2. 通常<br>c, d=10"]
    B --> C["3. *args<br>または * だけ"]
    C --> D["4. キーワード専用<br>e, g=20"]
    D --> E["5. **kwargs"]

5種類すべてを使った関数で確かめます。

import inspect

def f(a, b, /, c, d=10, *args, e, g=20, **kwargs):
    print(f"a={a} b={b} c={c} d={d} args={args} e={e} g={g} kwargs={kwargs}")

f(1, 2, 3, e=5)
f(1, 2, c=3, e=5)
f(1, 2, 3, 4, 5, 6, e=7, g=8, h=9)

for p in inspect.signature(f).parameters.values():
    print(f"{p.name:7} {p.kind.name}")

a=1 b=2 c=3 d=10 args=() e=5 g=20 kwargs={}
a=1 b=2 c=3 d=10 args=() e=5 g=20 kwargs={}
a=1 b=2 c=3 d=4 args=(5, 6) e=7 g=8 kwargs={'h': 9}
a       POSITIONAL_ONLY
b       POSITIONAL_ONLY
c       POSITIONAL_OR_KEYWORD
d       POSITIONAL_OR_KEYWORD
args    VAR_POSITIONAL
e       KEYWORD_ONLY
g       KEYWORD_ONLY
kwargs  VAR_KEYWORD

3つ目の呼び出しでは、位置引数6個のうち4個が a, b, c, d に入り、残りの 5, 6 が args に、名前の決まっていない h=9 が kwargs に入っています。

順番についての細かいルール

順番を入れ替えたときのエラーメッセージを、compile() で確かめました（Python 3.14.7）。

1行目のメッセージは、Python 3.11.15 では non-default argument follows default argument でした。表現は違いますが、同じ内容です。

キーワード専用引数（*）を使う場面

意味が伝わりにくい引数は、* の後ろに置いてキーワード専用にすると、呼び出し側が読みやすくなります。

def export(path, *, overwrite=False, encoding="utf-8"):
    ...

export("out.csv", overwrite=True)   # 何を True にしたのかが読める
# export("out.csv", True)           # TypeError になるので、この書き方は入り込まない

True／False や数値が位置で並ぶと、どれが何の指定なのかを関数定義まで見に行くことになります。キーワード専用にしておくと、名前つきで書くことが関数の側から決まります。

位置専用引数（/）を使う場面

引数の名前を呼び出し側に公開したくないときに / を使います。 あとで引数名を変えても、呼び出し側のコードに影響しません。また、**kwargs と同じ名前がぶつかるのを避けられます。

def with_kwargs(x, /, **kwargs):
    return x, kwargs

print(with_kwargs(1, x=2))

(1, {'x': 2})

x は位置専用なので、x=2 は kwargs 側に入ります。/ がなければ「x に値が2回渡された」という TypeError になる場面です。

呼び出し側のアンパック（*リストと**辞書）

呼び出すときの * と ** は、定義のときとは逆に「まとまりをばらして渡す」働きをします。 これをアンパックと呼びます。

def order(item, qty, price):
    return f"{item} x{qty} = {qty*price}"

row = ["ノート", 3, 300]
opt = {"item": "ペン", "qty": 2, "price": 150}

print(order(*row))                 # order("ノート", 3, 300) と同じ
print(order(**opt))                # order(item="ペン", qty=2, price=150) と同じ
print(order("付箋", *[5, 120]))     # 一部だけ展開
print(order(*("消しゴム",), **{"qty": 1, "price": 80}))

ノート x3 = 900
ペン x2 = 300
付箋 x5 = 600
消しゴム x1 = 80

* と ** は、関数呼び出し以外でも同じ考え方で使えます。

a = [1, 2]; b = [3]
print([*a, *b], {**{"x": 1}, **{"x": 2, "y": 3}})   # リスト・辞書の結合

first, *rest = [1, 2, 3, 4]                         # 代入の左辺でまとめる
print(first, rest)

print(*"abc", sep="-")                              # 文字列も展開できる

[1, 2, 3] {'x': 2, 'y': 3}
1 [2, 3, 4]
a-b-c

辞書の結合では、同じキーがあると後ろの値が残ります（x は 2）。

呼び出し側にも順番のルールがあります。

TypeErrorの代表パターンと直し方

引数まわりのエラーは、メッセージの形を覚えておくと原因がすぐにわかります。次の関数を使って再現します。

def two(a, b): return a + b
def greet(name, greeting="こんにちは"): return f"{greeting}、{name}"
def pos_only(x, y, /): return x + y
def kw_only(*, debug): return debug

特に見かけることが多いのは、次の3つです。

• missing … required positional argument：メソッド定義で self を書き忘れたとき、クラスをインスタンス化せずにメソッドを呼んだときにも出ます。
• got multiple values for argument：第1引数を位置で渡しつつ、同じ名前をキーワードや **辞書 でも渡したときに出ます。辞書を展開する前に opts.pop("name", None) で取り除くか、位置で渡すのをやめます。
• got an unexpected keyword argument：つづりの違いのほか、ライブラリのバージョンによって引数名が変わったときにも出ます。help(関数) や inspect.signature(関数) で受け付ける引数を確認できます。

**kwargs を持つ関数は、どんな名前のキーワード引数でも受け取るので、つづりを間違えても TypeError になりません。

def search(**kwargs): return kwargs
print(search(keyword='pen', limt=5))   # limit のつもり

{'keyword': 'pen', 'limt': 5}

決まった名前のオプションしか受け付けないなら、**kwargs ではなくキーワード専用引数として1つずつ書くと、間違いを呼び出しの時点で見つけられます。後述の TypedDict と Unpack を使う方法もあります。

デフォルト引数の使い方と、リストを置いたときの挙動

デフォルト引数は、呼び出し側が省略したときに使われる値です。 def greet(name, greeting="こんにちは") のように = で書きます。

デフォルト値は関数を定義したときに1回だけ評価される

def 文が実行された時点で既定値の式が計算され、その結果が関数オブジェクトに保存されます。呼び出しのたびに計算し直されるわけではありません。

def mk():
    print("  default evaluated"); return 0

print("before def")
def h(v=mk()): return v
print("after def"); h(); h()

n = 1
def use_n(v=n): return v
n = 99; print(use_n())

before def
  default evaluated
after def
1

default evaluated は def の時点で1回だけ表示され、h() を2回呼んでも表示されません。また、use_n の既定値は定義時の n（1）で、あとから n = 99 にしても変わりません。

直す前：デフォルト引数に空リストを置く

def add_item(item, items=[]):
    items.append(item); return items

print(add_item("a"))
print(add_item("b"))
print(add_item("c", []))
print(add_item("d"))
print(add_item.__defaults__)

['a']
['a', 'b']
['c']
['a', 'b', 'd']
(['a', 'b', 'd'],)

2回目の呼び出しで ['b'] ではなく ['a', 'b'] が返っています。 既定値のリストは定義時に1つだけ作られ、省略して呼ぶたびに同じリストが使われるためです。add_item.__defaults__ を見ると、関数が持っている既定値そのものが書き換わっていることがわかります。辞書（{}）や集合（set()）でも同じことが起きます。

直した後：Noneを既定値にして、関数の中で作る

def add_item2(item, items=None):
    if items is None:
        items = []
    items.append(item); return items

print(add_item2("a"))
print(add_item2("b"))

['a']
['b']

呼び出しのたびに新しいリストが作られるので、前回の結果が残りません。

同じ考え方は「現在時刻」にも当てはまります。

import datetime, time

def now_bad(ts=datetime.datetime.now()): return ts
x1 = now_bad(); time.sleep(0.05); x2 = now_bad(); print(x1 == x2)

def now_ok(ts=None): return ts if ts is not None else datetime.datetime.now()
y1 = now_ok(); time.sleep(0.05); y2 = now_ok(); print(y1 == y2)

True
False

now_bad は、何度呼んでも関数を定義した時刻を返します。None を既定値にして中で now() を呼ぶと、呼び出しごとの時刻になります。

None も有効な値として渡したいときは、目印用のオブジェクトを既定値にします。

_MISSING = object()

def update(name, note=_MISSING):
    if note is _MISSING:
        return f"{name}: noteは変更なし"
    return f"{name}: note={note!r}"

print(update("a"))
print(update("a", None))

a: noteは変更なし
a: note=None

*argsと**kwargsの型ヒント

*args: int は「args の要素1つ1つが int」という意味で、args 全体の型は tuple[int, ...] になります。 **kwargs: str は「値が str」で、全体は dict[str, str] です。*args: tuple[int, ...] と書くと「タプルを何個でも受け取る」という別の意味になります。

from typing import TypedDict, Unpack, NotRequired


def total(*args: int) -> int:
    return sum(args)


def labels(**kwargs: str) -> list[str]:
    return [f"{k}={v}" for k, v in kwargs.items()]


class SearchOptions(TypedDict):
    keyword: str
    limit: NotRequired[int]
    desc: NotRequired[bool]


def search(**kwargs: Unpack[SearchOptions]) -> str:
    limit = kwargs.get("limit", 10)
    return f"{kwargs['keyword']} limit={limit} desc={kwargs.get('desc', False)}"


print(search(keyword="pen", limit=5))

pen limit=5 desc=False

型チェッカー mypy 1.20.2 で reveal_type() を使って確かめると、args は tuple[int, ...]、kwargs は dict[str, str] と表示されました。

キーごとに型が違うときは TypedDict と Unpack

**kwargs: str は、すべての値が同じ型のときにしか使えません。キーごとに型が違う場合は、TypedDict で名前と型を定義し、**kwargs: Unpack[SearchOptions] と書きます（PEP 692。Python 3.12 で正式に導入されました。typing.Unpack と NotRequired は 3.11 にもあり、上のコードは 3.11.15 でも実行できました）。

間違った呼び出しを mypy 1.20.2 にかけた結果です。

**kwargs のままでも、つづりの違い・必須キーの不足・型の違いをコードを動かす前に見つけられます。 実行時には型ヒントによる検査は行われないので、型チェッカーやエディタの補完と組み合わせて使います。

型ヒント全般の書き方は、既存記事「Pythonの型ヒントの書き方」で扱っています。

デコレータでの引数転送の定型

*args, **kwargs がもっともよく使われるのは、受け取った引数をそのまま別の関数へ渡す場面です。デコレータ（関数に前後の処理を足す仕組み）では、次の形が定型になります。

import functools, inspect

def log_calls(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"call {func.__name__} args={args} kwargs={kwargs}")
        result = func(*args, **kwargs)
        print(f"  -> {result!r}")
        return result
    return wrapper

@log_calls
def area(width, height=1, *, unit="cm"):
    """面積を返す"""
    return f"{width*height}{unit}2"

area(3, 4)
area(5, unit="m")
print(area.__name__, area.__doc__, inspect.signature(area))

call area args=(3, 4) kwargs={}
  -> '12cm2'
call area args=(5,) kwargs={'unit': 'm'}
  -> '5m2'
area 面積を返す (width, height=1, *, unit='cm')

ポイントは3つです。

• wrapper(*args, **kwargs) でまとめて受け取り、func(*args, **kwargs) でばらして渡す。 元の関数の引数がどんな形でも、そのまま通せます。
• @functools.wraps(func) を付けると、関数名・docstring・シグネチャが元の関数のものとして見えます。
• 型ヒントを付けるときは ParamSpec を使うと、デコレータを通しても引数の型が保たれます。

from typing import Callable, ParamSpec, TypeVar
import functools

P = ParamSpec("P")
R = TypeVar("R")

def log_calls(func: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"call {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

この形で area("3") や area(3, unit=1) を mypy 1.20.2 にかけると、Argument 1 to "area" has incompatible type "str"; expected "int"、Argument "unit" to "area" has incompatible type "int"; expected "str" と、元の関数の型に沿って検出されました（area の引数に int・str の型ヒントを付けた場合）。

継承でも同じ形が使えます。子クラスで追加の引数だけを取り出し、残りを親クラスへ渡します。

class Base:
    def __init__(self, name, *, active=True):
        self.name, self.active = name, active

class Member(Base):
    def __init__(self, *args, rank="regular", **kwargs):
        super().__init__(*args, **kwargs)
        self.rank = rank

m = Member("田中", active=False, rank="gold")
print(m.name, m.active, m.rank)

田中 False gold

デコレータの作り方やレシピは、既存記事「Pythonデコレータの使い方」にまとめています。

functools.partialで引数の一部を固定する

functools.partial は、関数の引数の一部をあらかじめ埋めた新しい関数を作ります。 「引数を受け取って転送する」*args, **kwargs と対になる道具です。

from functools import partial

def power(base, exp): return base ** exp

square = partial(power, exp=2)
print(square(5), square.func.__name__, square.args, square.keywords)
print(square(5, exp=3))        # キーワードで固定した値は上書きできる

two_pow = partial(power, 2)    # 位置で固定すると先頭の引数が埋まる
print(two_pow(10))

print(list(map(partial(int, base=2), ["101", "111"])))

p = partial(print, sep=" | ", end=" <\n")
p("a", "b")

25 power () {'exp': 2}
125
1024
[5, 7]
a | b <

位置で固定した引数を、呼び出し時にキーワードでもう一度渡すと TypeError になります。partial(power, 2)(base=3) の実行結果は power() got multiple values for argument 'base' でした。

partial は、map や sorted の key、コールバックのように「引数の数が決まっている場所へ関数を渡す」場面で使いやすくなります。lambda x: power(x, 2) と書いても同じ結果になりますが、partial で作った関数は .func・.args・.keywords で中身を確認できます。

*argsと**kwargsを使うかどうかの判断表

よくある質問

Q. args と kwargs という名前でなければいけませんか？ A. 名前は自由です。意味を持つのは * と ** で、この記事の *prices や **attrs のように中身を表す名前にできます。そのまま別の関数へ渡すだけの場合は、慣習どおり *args, **kwargs と書くと、読む人に意図が伝わりやすくなります。

Q. *args の後ろに普通の引数を書くとどうなりますか？ A. キーワード専用引数になります。def f(*args, sep="-") の sep は、f(1, 2, sep="/") のように名前を付けたときだけ渡せます。位置で渡した値はすべて args に入ります。

Q. **kwargs で受け取った辞書を書き換えると、呼び出し元の辞書も変わりますか？ A. 変わりません。f(**opt) と呼んだとき、関数の中の kwargs は新しく作られた辞書です。kwargs["x"] = 1 と追加しても、kwargs.pop("x") と取り除いても、元の opt はそのままです。ただし、値として入っているリストなどのオブジェクト自体は共有されています。

Q. デフォルト引数に空リストを書きたいときはどうすればよいですか？ A. items=None と書き、関数の先頭で if items is None: items = [] とします。この記事の実行結果のとおり、items=[] と書くと定義時に作られた1つのリストが呼び出しのたびに使われ、前回の値が残ります。

まとめ

• *args は余った位置引数をタプルで、**kwargs は余ったキーワード引数を辞書で受け取る。名前は自由で、記号に意味がある
• 引数の順番は「位置専用 / → 通常 → *args → キーワード専用 → **kwargs」。入れ替えると SyntaxError になる
• 呼び出し側の *リスト・**辞書 はアンパック。定義側の「まとめる」と向きが逆
• TypeError はメッセージの形で原因がわかる。missing、multiple values、unexpected keyword、positional-only の4つを押さえる
• デフォルト値は定義時に1回だけ評価される。リスト・辞書・現在時刻は None を既定値にして関数の中で作る
• 型ヒントは *args: int（要素の型）と **kwargs: Unpack[TypedDict]。デコレータは ParamSpec で元の引数の型を保てる
• 受け取って転送するなら *args, **kwargs、一部を固定するなら functools.partial

株式会社RJCでは、Pythonの引数の仕組みのような基礎を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。