Python CLI工具pip安装后未加入路径问题及配置咨询

一、pyproject.toml配置检查 #

1. 包结构验证 #

你的src目录必须被识别为Python包，才能让src.main:main被正确引用。务必在src文件夹下创建空的__init__.py文件——没有这个文件的话，setuptools的find={}规则不会把src当作包打包，导致shell找不到命令入口。

2. 脚本路径正确性 #

[project.scripts]里的格式是包名.模块名:函数名，确认src/main.py中的main函数是可直接调用的入口。另外检查src/main.py里的依赖导入是否完整，比如代码里的load_dotenv需要加上from dotenv import load_dotenv，cli也要确保有对应的导入，避免运行时报错。

3. 本地安装测试验证 #

在项目根目录执行本地安装命令，快速验证配置是否正常：

pip install -e .

如果安装后能直接调用wd-cli或wd，说明配置本身没问题，问题出在系统PATH上。

二、Shell路径配置（Mac zsh/Windows） #

1. Mac zsh环境配置 #

pip全局安装的Python脚本一般存在以下位置，需要把这个路径加入系统PATH：

步骤1：定位脚本安装路径

执行命令查看包的安装位置，再拼接/bin得到脚本目录：

pip show wd-cli | grep Location

比如输出是/Users/xxx/Library/Python/3.9/site-packages，那脚本目录就是/Users/xxx/Library/Python/3.9/bin。

步骤2：修改.zshrc

打开配置文件：

open ~/.zshrc

在文件末尾添加路径（替换成你自己的路径）：

export PATH="$PATH:/Users/xxx/Library/Python/3.9/bin"

保存后执行以下命令让配置生效：

source ~/.zshrc

2. Windows环境配置 #

Windows下pip安装的脚本通常在%APPDATA%\Python\PythonXY\Scripts（XY是Python版本号，比如39），或者Python安装目录的Scripts文件夹。

步骤1：定位脚本路径

打开命令提示符，执行：

pip show wd-cli | findstr Location

在输出的路径后加上\Scripts，就是脚本所在目录。

步骤2：添加到系统环境变量

• 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
• 在「系统变量」中找到Path，点击「编辑」
• 添加找到的Scripts目录路径，点击「确定」
• 重启命令提示符或PowerShell后生效

三、额外建议 #

• 推荐用户用虚拟环境安装工具，激活虚拟环境后命令会自动加入当前shell的PATH，避免全局路径混乱。
• Mac用户如果是用Homebrew安装的Python，脚本可能在/usr/local/bin，可以先检查这个目录是否已经在PATH里。

内容的提问来源于stack exchange，提问作者Snake_py