一、pip/setuptools修改shebang的工作机制 #

当你用pip3 install安装带有scripts字段的Python包时，背后是setuptools在处理脚本的安装逻辑。它这么做的核心目的是确保脚本运行时使用的是安装该包的那个Python解释器，避免系统里多Python版本共存导致的环境混乱。

具体逻辑是：

• setuptools会扫描你指定的脚本文件，定位开头的shebang行（也就是第一行的#!/path/to/python或#!/usr/bin/env pythonX）；
• 它会把这个shebang替换成当前执行pip3的Python解释器绝对路径——比如你用MacPorts装的Python3.5，路径可能是#!/opt/local/bin/python3.5；
• 如果脚本没有shebang行，setuptools会自动添加一个指向当前Python解释器的shebang。

这种修改是默认行为，能保证脚本安装后，无论用户PATH环境变量怎么设置，都能调用到正确的Python版本运行你的包脚本。

二、为什么脚本的第二行会影响pip的安装行为？ #

这和setuptools检测shebang的逻辑直接相关：

• setuptools默认只把文件第一行当作shebang处理，但如果第一行不是有效shebang（比如是空行或普通注释），它会继续检查第二行；
• 要是第二行包含类似shebang的内容（比如误写了#!/usr/bin/env python在第二行），或者编码声明/注释格式不符合预期，就会干扰检测逻辑：
  • 比如第一行空白、第二行才是shebang，setuptools会识别第二行并修改；
  • 如果第二行内容让setuptools误以为这不是Python脚本（比如包含非Python的命令行语法），它可能跳过shebang修改，导致脚本运行时用错Python版本；
• 当然，正常的第二行编码声明（比如# -*- coding: utf-8 -*-）不会影响，但如果格式出错（比如少了-*-），可能被误判为无效内容，间接干扰shebang处理流程。

三、如何控制shebang的修改行为？ #

如果你想避免setuptools修改脚本shebang，或者自定义规则，可以试试这几种方法：

1. 用console_scripts替代scripts #

在setup.py里，推荐用console_scripts字段代替scripts，它会生成setuptools管理的wrapper脚本，不会直接修改你的原脚本：

setup(
    # ...其他配置项...
    entry_points={
        'console_scripts': [
            'somscript = mypackage.module:main_function',
        ],
    }
)

这种方式下，setuptools会自动生成指向正确Python解释器的脚本，你的原代码不需要包含shebang，也不会被改动。

2. 禁用shebang修改（针对scripts字段） #

如果坚持用scripts，可以在setup.py里设置options参数，告诉setuptools不要修改shebang：

setup(
    # ...其他配置项...
    scripts=['bin/somscript'],
    options={
        'build_scripts': {
            'executable': None,  # 保留原脚本shebang，不做修改
        }
    }
)

要是想指定自定义shebang路径，把executable设为你想要的内容即可，比如'/usr/bin/env python3'。

3. 规范脚本的shebang格式 #

确保脚本第一行是标准shebang，避免第二行出现类似shebang的内容，比如：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# 后续Python代码...

这样setuptools能正确识别第一行shebang，按规则修改（或者用上面的方法禁用修改）。

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