Linux/Mac下怎么通过Shebang和chmod直接运行Python脚本

假设你编写了一个日常使用的自动化处理脚本 clean_cache.py，每次需要调用它时，都必须打开终端键入 python3 clean_cache.py。当这个脚本需要频繁使用，或者希望它能像系统自带的 git、curl、ls 等命令一样随叫随到时，每次显式输入解释器名字就显得繁琐。在 Linux 与 macOS 系统中，将 Python 脚本转变为独立可执行程序只需要两个步骤：在脚本第一行写入 Shebang 声明解释器，并使用 chmod 赋予其执行权限。完成之后，直接输入 ./clean_cache.py 即可立刻运行。

一、两步搞定：具体操作流程与完整示例

要让操作系统把 Python 代码当作独立程序执行，内核必须解决两个核心问题：第一，当前文件是否有执行权限；第二，该文件应该由谁来负责解释执行。下面按顺序完成标准配置。

第一步：在脚本首行添加 Shebang 声明

使用文本编辑器打开脚本，在文件的第一行顶格输入以下内容：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import sys

def main():
    print("Python 脚本正在以独立命令方式运行！")
    print(f"当前 Python 解释器路径: {sys.executable}")

if __name__ == "__main__":
    main()

这里开头的 #!/usr/bin/env python3 就是常说的 Shebang（由 # Hash 和 ! Bang 组合而成）。它告诉操作系统：请启动 /usr/bin/env 程序，并在系统当前的环境变量 $PATH 中寻找可用的 python3 来解释后续代码。

第二步：使用 chmod 为脚本添加可执行权限

在 Linux 和 macOS 中，新建的普通文本文件默认权限通常是 644（即文件所有者可读可写，其余人只读），缺少执行权限（x 标志位）。打开终端，切换到脚本所在目录，执行以下命令：

chmod +x clean_cache.py

该命令会为文件的所有者、用户组和其他用户同时添加可执行权限。如果希望权限更收敛，也可以只给当前用户赋予执行权限：chmod u+x clean_cache.py。

第三步：直接在终端中运行验证

赋予权限后，无需再输入 python3，直接在终端中调用该文件：

./clean_cache.py

终端示例输出：

Python 脚本正在以独立命令方式运行！
当前 Python 解释器路径: /usr/local/bin/python3

注意开头的 ./：Unix 系统出于安全防范考虑，当前目录 . 默认不会包含在环境变量 $PATH 中，以防止同名恶意脚本劫持系统基础命令。因此在当前目录下执行自身时，必须显式加上相对路径 ./。

二、底层原理：当你输入 ./script.py 时，操作系统在做什么？

理解操作系统底层的执行逻辑，有助于在遇到异常时快速定位根因。当你在 Bash、Zsh 或其它终端中键入 ./clean_cache.py 并回车时，底层会发生以下调用流程：

1. Shell 发起系统调用：终端 Shell 会通过 fork() 创建子进程，并在子进程中调用 execve("./clean_cache.py", argv, envp) 请求内核加载程序。
2. 内核检查权限位（Permission Check）：操作系统内核读取该文件的元数据 inode。如果发现当前用户对应权限位中没有 x（Execute），系统调用立刻拒绝并抛出 EACCES 错误，终端直接打印 Permission denied。
3. 魔数识别（Magic Number）：内核读取文件最开始的 2 个字节。如果前两个字节是 0x23 0x21（即 ASCII 字符 #!），内核即判定这是一个脚本文件，而非 ELF 或 Mach-O 二进制文件。
4. 解析解释器路径：内核会截取第一行 #! 后面的内容（去掉首尾空格），提取出解释器路径 /usr/bin/env，并提取后续参数 python3。
5. 重构并执行进程：内核将实际执行目标转换为 /usr/bin/env python3 ./clean_cache.py，完成最终的 Python 解释器加载与代码执行。

三、核心细节：为什么推荐 /usr/bin/env python3 而非绝对路径？

在编写 Shebang 时，有两种常见写法：

• #!/usr/bin/python3（指定绝对物理路径）
• #!/usr/bin/env python3（通过 env 工具动态查找）

绝大多数生产和开源项目中均强烈推荐第二种写法。其核心原因如下：

• 多环境路径差异：在不同的系统和安装方式下，Python3 的安装路径差异极大。macOS 上通过 Homebrew 安装的 Python 位于 /opt/homebrew/bin/python3（Apple Silicon）或 /usr/local/bin/python3（Intel），而部分 Linux 发行版则将其安装在 /usr/bin/python3。若硬编码绝对路径，脚本复制到另一台机器就会因“找不到解释器”而直接崩溃。
• 完美兼容虚拟环境（venv）：当你在终端中执行 source venv/bin/activate 激活了 Python 虚拟环境时，激活脚本会将该虚拟环境的 bin/ 目录置于系统环境变量 $PATH 的最前端。此时使用 /usr/bin/env python3 会自动匹配虚拟环境中的 Python，所有在虚拟环境中安装的第三方依赖库均可正常导入；而绝对路径则会强制调用系统全局 Python，导致 ModuleNotFoundError。

四、常见故障与避坑指南

在日常使用中，初学者常常会遇到以下三个典型问题：

1. 报错 /usr/bin/env: 'python3\r': No such file or directory

这是在跨平台开发中最容易碰到的经典问题。如果你在 Windows 环境的编辑器（如 VS Code）中创建或编辑过脚本，文件保存时的换行符往往是 Windows 标准的 CRLF（\r\n）。

当该文件被拷贝到 Linux 或 Mac 上执行时，Unix 内核只会识别 \n 为行结束符，于是把行末不可见的 \r 视作程序名称的一部分，导致内核在寻找名为 python3\r 的命令，最终报错提示找不到文件。

解决办法：将文件换行符转为 Unix 标准的 LF（\n）。在终端中可以使用以下命令一键修复：

# Linux 系统下安装并使用 dos2unix
dos2unix clean_cache.py

# 或在 macOS / Linux 下使用 sed 移除行末的 \r
sed -i '' 's/\r$//' clean_cache.py   # macOS
sed -i 's/\r$//' clean_cache.py      # Linux

2. Shebang 之前不能有空行或注释

Unix 内核在检查魔数时，只读取文件偏移量 0（Offset 0）处的字节。如果文件第一行是空行，或者第一行写了其他普通注释，内核读取到的前两个字节就不是 0x23 0x21。内核会因此判定该文件不是 Shebang 脚本，并回退给默认 Shell（如 bash/zsh）作为 Shell 脚本运行，导致各种奇奇怪怪的 Python 语法错误（例如 syntax error near unexpected token）。

3. 终端提示 Permission denied

说明尚未为该文件赋予执行权限。只需重新执行 chmod +x clean_cache.py 即可解决。可以通过 ls -l clean_cache.py 查看文件权限字符串，确认是否包含 x 标志位。

五、进阶技巧：打造真正的全局系统命令

如果你希望在系统的任何目录都能像运行 ls 或 git 一样直接键入脚本名，而不需要指定当前目录 ./，可以采取以下进阶优化：

1. 去掉脚本的 .py 扩展名

在 Linux 和 macOS 中，可执行程序并不依赖文件扩展名来识别文件类型（Windows 则依赖 .exe、.bat）。你可以直接重命名文件：

mv clean_cache.py clean_cache

这样在终端中直接运行 ./clean_cache，命令看起来更加原生、干练。

2. 将脚本放入用户 PATH 目录

把脚本移动到系统环境变量 $PATH 包含的目录中，例如个人用户的常用目录 ~/.local/bin 或全局目录 /usr/local/bin：

# 移动至当前用户的个人 bin 目录
mkdir -p ~/.local/bin
mv clean_cache ~/.local/bin/

# 如果 ~/.local/bin 已在 PATH 中，即可在任何目录直接键入命令：
clean_cache --help