# argparse 超簡單教學：讓 Python 小工具聽懂你的指令
這份只講 `argparse` 最基本的概念。
你可以把它想成：幫你的 Python 程式加上一個「可以聽懂人類指令」的入口。
例如原本你的程式可能只會傻傻固定執行；
加了 `argparse` 之後，你就可以在啟動時告訴它：
– 要處理哪個檔案
– 要跑幾次
– 要不要開啟 debug
– 要用哪一種模式
不綁任何專案，也不假設你已經在寫 CLI 工具。
## 1. `argparse` 是做什麼的
`argparse` 是 Python 內建模組。
它的用途很單純：
– 讓 Python 程式可以接收啟動參數
– 把參數整理成好讀的 `args.xxx`
它最常見的用途其實就是把 Python 腳本
變成一個比較像「小工具」的東西。
常見情境像：
– `python resize.py –input a.jpg –width 300`
– `python report.py –month 2026-05 –debug`
– `python hello.py –name Mochi –times 3`
也就是說，`argparse` 的核心價值不是炫技，
而是讓同一支程式可以根據你輸入的參數，做不同的事。
例如你執行：
“`bash
python demo.py –name Mochi –times 3
“`
`argparse` 會幫你把這些參數解析成：
– `args.name` 會是 `”Mochi”`
– `args.times` 會是 `3`
## 2. 最小範例
# %%
import argparse
parser = argparse.ArgumentParser(description="Repeat a greeting")
parser.add_argument("--name", default="Mochi")
parser.add_argument("--times", type=int, default=3)
args = parser.parse_args(["--name", "Mochi", "--times", "3"])
for turn in range(args.times):
print(f"{turn + 1}. Hello, {args.name}!")這裡 `–name` 沒有特別寫 `type`，
是因為 `argparse` 預設就會把它當成字串 `str`。
所以 `parser.add_argument(“–name”)` 和
`parser.add_argument(“–name”, type=str)`
在這種情況下效果一樣。
上面故意寫成 `parse_args([“–name”, “Mochi”, “–times”, “3”])`，
是因為這樣可以直接貼進 Jupyter 跑。
如果你是在真正的 `.py` 檔用 terminal 執行，通常才會改回：
args = parser.parse_args()如果你這樣執行：
python demo.py --name Mochi --times 3輸出就會是：
## 3. 最常見的 3 種參數
### 3.1 一般文字參數
parser.add_argument("--name")執行：
python demo.py --name Mochi參數解析後：
args.name # "Mochi"如果你看的不是「單一參數 `args.name` 的值」，而是前面那個完整 greeting 範例，
那它會不會印 3 次，還要再看 `args.times` 是多少。
### 3.2 指定型別
parser.add_argument("--times", type=int)執行：
python demo.py --times 3參數解析後：
args.times # 3這裡只是在看 `args.times` 這個參數最後被解析成什麼值。
如果是完整程式最終會印幾次，還要再看程式裡有沒有用 `args.times` 去控制迴圈。
注意：這裡會是整數 `3`，不是字串 `”3″`。
### 3.3 開關型參數
parser.add_argument("--debug", action="store_true")執行：
python demo.py --debug參數解析後：
args.debug # True如果沒帶 `–debug`，就是：
args.debug # False這種開關型參數，`argparse` 的標準寫法就是：
parser.add_argument("--debug", action="store_true")意思是：
– 有帶 `–debug` -> `args.debug` 會是 `True`
– 沒帶 `–debug` -> `args.debug` 會是 `False`
通常不建議直接寫成 `type=bool`，因為命令列傳進來的是字串，
像 `”False”` 這種文字在 Python 裡不一定會照你直覺變成布林 `False`，反而很容易造成誤解。
這種最適合用來表示：
– 是否開啟 debug
– 是否使用某個模式
– 是否輸出更多資訊
terminal :
python -c "import argparse; parser=argparse.ArgumentParser(); parser.add_argument('--debug', action='store_true'); print(parser.parse_args(['--debug']).debug)"no flag -> False
with flag -> True
## 4. `default` 是什麼
你可以給參數預設值：
parser.add_argument("--times", type=int, default=1)這表示如果使用者沒帶 `–times`，就自動用 `1`。
例如：
“`bash
python demo.py –name Mochi
“`
那麼：
“`python
args.times # 1
“`
## 5. `required=True` 是什麼
如果某個參數一定要提供，可以這樣寫：
“`python
parser.add_argument(“–name”, required=True)
“`
如果你沒帶：
“`bash
python demo.py
“`
`argparse` 會直接報錯，提醒你缺少 `–name`。
## 6. `parse_args()` 在做什麼
這一行是關鍵：
“`python
args = parser.parse_args()
“`
意思是：
– 去讀這次啟動程式時帶進來的參數
– 解析完後回傳到 `args`
如果你改成：
“`python
args = parser.parse_args([“–name”, “Mochi”, “–times”, “3”])
“`
那就不是讀外部啟動參數，而是直接解析你手動給它的這串參數。
這種寫法很適合 notebook。
所以後面你就可以寫：
print(args.name)
print(args.times)## 7. 最常見的完整範例
import argparse
parser = argparse.ArgumentParser(description="Simple argparse demo")
parser.add_argument("--name", required=True)
parser.add_argument("--times", type=int, default=1)
parser.add_argument("--debug", action="store_true")
args = parser.parse_args(["--name", "Mochi", "--times", "3", "--debug"])
if args.debug:
print("debug mode on")
for turn in range(args.times):
print(f"{turn + 1}. Hello, {args.name}!")這段可以直接貼進 Jupyter 執行。
如果你改成真正的 `.py` 檔搭配 terminal，等價指令會是：
python demo.py --name Mochi
python demo.py --name Mochi --times 3
python demo.py --name Mochi --times 3 --debug## 8. 在 Jupyter 怎麼理解
如果你只是想學概念，可以先這樣記：
– `parse_args()`：讀真正啟動時帶進來的參數
– `add_argument(…)`：定義這個程式接受哪些參數
但要注意：在 Jupyter / notebook 裡，直接寫這種：
“`python
args = parser.parse_args()
“`
很常會報錯，像：
usage: ipykernel_launcher.py [-h] [--name NAME] [--times TIMES]
ipykernel_launcher.py: error: unrecognized arguments: --f=...kernel-xxxx.json原因不是你的程式壞掉，而是 notebook kernel 啟動 Python 時，自己額外帶了像 `–f=…` 這類參數。
你的 `argparse` 不認得它，就會報 `unrecognized arguments`。
所以在 notebook 裡，初學時最簡單的做法不是直接用 `parse_args()`，而是自己手動傳一組參數。
例如在 terminal 裡，你原本可能是這樣跑：
“`bash
python demo.py –name Bob
“`
但在 notebook 裡，比較建議改成：
“`python
args = parser.parse_args([“–name”, “Bob”, “–times”, “3”])
“`
如果你只是想測預設值，可以用：
“`python
args = parser.parse_args([])
“`
如果真的要在 notebook 測，也可以手動傳一組參數：
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--name")
parser.add_argument("--times", type=int, default=1)
args = parser.parse_args(["--name", "Bob", "--times", "3"])
print(args)這樣也能看到：
如果你想讓它忽略 notebook 額外塞進來、但你沒定義的參數，也可以用：
args, unknown = parser.parse_known_args()
print(args)
print(unknown)這種方式會把認得的參數放進 `args`，不認得的放進 `unknown`，因此不會直接報錯。
## 9. 一句話記法
你可以把 `argparse` 記成：
– `add_argument(…)`：先宣告這個程式接受哪些參數
– `parse_args()`：再把外部傳進來的參數解析成 `args.xxx`
## 9.1 `-n` 和 `–name` 有什麼差別
在 `argparse` 裡，最常見的慣例是：
– `–name`：長參數
– `-n`：短參數
例如你可以這樣寫：
“`python
parser.add_argument(“-n”, “–name”, default=”Mochi”)
“`
這表示下面兩種寫法都可以：
“`bash
python demo.py –name Mochi
python demo.py -n Mochi
“`
最後都會進到同一個：
“`python
args.name
“`
通常不建議寫成 `-name`，因為命令列工具的常見慣例是：
– 單一短橫 `-` 給短參數，例如 `-n`
– 雙短橫 `–` 給長參數，例如 `–name`
## 10. 初學者最常卡的地方
– `–debug` 這種 `store_true` 不用再寫 `True`，有帶就代表開啟
– `type=int` 會自動幫你把字串轉成整數
– `default=…` 是沒給參數時才使用
– `required=True` 是強制一定要給
– `args.xxx` 的名字通常來自參數名，例如 `–max-retries` 會變成 `args.max_retries`
## 11. 最短總結
最常見的流程只有 3 步：
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--name")
args = parser.parse_args()
print(args.name)如果你看懂這 3 行，`argparse` 就已經入門了。
推薦hahow線上學習python: https://igrape.net/30afN