直接运行 python setup.py install 会出错，因其在Python 3.12+已被弃用，且忽略pyproject.toml配置；应优先使用pip install .或pip install -e .。
直接运行 python setup.py install 会出错？先确认 Python 环境和 setuptools 是否就位
很多报错其实不是 setup.py 本身的问题，而是环境缺依赖或权限混乱。Python 3.12+ 已默认不带 easy_install，setuptools 也得手动确保是较新版本（≥60.0）。运行前先检查：
-
python -m pip list | grep setuptools—— 如果没输出或版本太老，先python -m pip install --upgrade setuptools -
which python和which pip要指向同一环境，尤其在用 pyenv、conda 或系统多 Python 共存时 - 别用
sudo python setup.py install：它可能把包装进系统 site-packages，后续 pip 管理失效；改用pip install --user .（点号代表当前目录）更安全
pip install . 和 python setup.py install 本质区别在哪
前者走的是 PEP 517 构建流程，会自动调用 build-backend（通常是 setuptools.build_meta），生成 wheel 再安装；后者是旧式直接执行，跳过构建阶段，容易忽略 pyproject.toml 配置、不兼容现代元数据规范。
- 如果包根目录有
pyproject.toml，pip install .是唯一推荐方式；setup.py可能被完全忽略 -
python setup.py install在 Python 3.12+ 中已被标记为 deprecated，部分新字段（如dynamic版本）根本不会生效 - 想本地开发调试？用
pip install -e .（-e 表示 editable mode），改源码不用重装
解压 tar.gz 后发现没有 setup.py？可能是纯 PEP 517 包或已废弃项目
不是所有 tar.gz 都含 setup.py。近年越来越多项目只保留 pyproject.toml + src/ 结构，或者干脆是 C 扩展包但依赖 meson / scikit-build-core 等非 setuptools 构建后端。
- 先
tar -tzf package-1.2.3.tar.gz | head -20看顶层文件，找pyproject.toml或setup.cfg - 如果有
pyproject.toml且[build-system]指定了requires（比如["meson-python"]），就得先pip install meson-python再pip install . - 若只有
setup.cfg没setup.py，说明项目用的是旧式配置驱动，仍可用pip install .，但需setuptools >= 45.0
安装后模块 import 失败？路径、命名和 __init__.py 常被忽略
即使安装成功，import mypackage 报 ModuleNotFoundError 很常见——问题往往不在安装过程，而在包结构本身。
立即学习“Python免费学习笔记（深入）”；
- 检查解压后的目录结构：顶级目录名（如
requests-2.31.0/）≠ 包名（requests）；真正 import 的是requests/子目录下的内容 - 确保
src/目录下有对应包名的子目录，且每层都有__init__.py（哪怕空文件）；否则 Python 不认它是包 - 安装后可查位置：
python -c "import mypackage; print(mypackage.__file__)"，确认路径是否在site-packages里，而不是你误操作的当前目录
setup.py 还是 pyproject.toml，又或者 pip install . 报了一堆构建错误但提示信息藏在中间几行。这时候别急着重试，先 cat pyproject.toml 看 [build-system]，再根据 require 列表装对应的构建工具——省掉一半排查时间。 
