你有沒有寫過一個 Python 工具，每次要用都得先 cd
進去那個目錄，然後 python main.py ...？
這篇文章要解決這個問題。透過 Python 標準的封裝機制，讓你的工具變成像
git、npm 一樣可以在任何地方直接呼叫的全域指令。
最終效果
封裝完成後，從任何目錄都能直接執行：
# 封裝前 cd /path/to/my-tool python main.py list --site aroot # 封裝後 orca-wp list --site aroot前置條件
你已經有一個用 Typer 或 Click 寫好的 CLI 工具，進入點大概長這樣：
# main.py import typer app = typer.Typer() @app.command() def hello(name: str): print(f"Hello, {name}!") if __name__ == "__main__": app()Step 1：建立 setup.py
在專案根目錄建立 setup.py：
from setuptools import setup setup( name="my-tool", version="1.0.0", description="我的 CLI 工具", py_modules=["main"], # 你的主程式檔名（不含 .py） install_requires=[ "typer>=0.9", "rich>=13", ], entry_points={ "console_scripts": [ "my-tool=main:app", # 指令名稱=檔案名稱:typer app 變數 ], }, python_requires=">=3.10", )關鍵在 entry_points 裡的 console_scripts：
my-tool：安裝後可在 terminal 使用的指令名稱main:app：main.py裡名為app
的物件（Typer / Click app）
Step 2：用 pip install -e . 安裝
pip install -e .-e 是 editable 模式，意思是：安裝後直接指向你的原始碼目錄，修改
main.py 立即生效，不需要重新安裝。
安裝完成後確認：
which my-tool # → /Users/yourname/anaconda3/bin/my-tool my-tool --help多個模組的情況
如果你的工具拆成多個 .py 檔，在 py_modules
裡列出所有需要的模組：
setup( ... py_modules=["main", "wp_client", "utils"], ... )如果是整個套件目錄（有 __init__.py），改用
packages：
from setuptools import setup, find_packages setup( ... packages=find_packages(), ... )如何讓新機器也能安裝
把專案放到 Git（GitHub / Bitbucket），新機器上的流程就是：
git clone [email protected]:yourname/my-tool.git cd my-tool pip install -e .後續更新只需要：
git pull # 不需要重新 pip install注意事項
- 指令名稱建議用小寫加連字號，例如
orca-wp、my-tool，可讀性比mytool好 - 含帳密的設定檔（如
config.json）記得加進
.gitignore - 如果同一環境有多個 Python 版本，確認
pip
對應的是你要用的版本（可用pip3或指定python3 -m）
pip - Anaconda 環境下安裝的指令會在
~/anaconda3/bin/，確認這個路徑在
$PATH裡
完整範例：orca-wp
這是我日常用來管理多個 WordPress 站台的工具實際的 setup.py：
from setuptools import setup setup( name="orca-wp-cli", version="1.0.0", description="WordPress CLI 工具 - 在終端管理你的 WP 站台", py_modules=["main", "wp_client"], install_requires=[ "typer>=0.9", "httpx>=0.27", "rich>=13", "python-dotenv", ], entry_points={ "console_scripts": [ "orca-wp=main:app", ], }, python_requires=">=3.10", )安裝後，不管在哪個目錄，直接跑 orca-wp list --site myblog
就能列出文章。工具的原始碼還在原本的目錄，改了馬上生效，不需要重新 build
或安裝。
這個方式對於個人工具、內部自動化腳本來說非常實用——不需要打包成
binary、不需要上 PyPI，只要一台有 Python 的機器，clone 下來 pip install
就能用。
常見問題 FAQ
為什麼要用 setup.py 封裝 CLI 工具？
setup.py 可以把套件與 entry point 定義好，讓指令安裝後就能在任何目錄直接執行。
CLI 工具和一般 Python 腳本有什麼差別？
封裝成 CLI 後更容易安裝、分發與維護，也更適合團隊或多機器環境使用。
什麼情境適合把工具做成全域指令？
當你需要反覆使用、跨專案呼叫，或希望其他人不用記 Python 執行路徑就能使用時，就很適合。
