1. 在 ARM 板上补齐代码开发工具:源码编译 Python 3.9 的取舍
手上有一块 ARM 架构的 Linux 开发板,系统自带的那份 Python 跟现场测试环境的小版本对不上,而从测试环境导出的 requirements.txt 只有在同版本上才装得干净。这时候代码开发工具这件事就绕不过去了:要么在板上找一份现成的包,要么自己编译一份完整的 Python 3.9,再把它整目录搬走。我走的是后一条路,理由很实际——只有源码编译能把解释器装进自己指定的目录,后面建虚拟环境、打包给别的机器用,路径全都可控。整套流程跑下来并不慢,真正让人翻车的是编译完之后拿错了解释器。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的安装落点:--prefix 决定后面所有路径
在板上敲第一条命令之前,先把两件事想清楚:为什么要自己编译,以及编译出来的东西最终落在哪里。这两个问题没想明白,后面每一条命令都是在猜。我见过太多人把源码目录当成安装目录,make 完就在源码树里建虚拟环境,结果换台机器解压出来全是 No module named 'encodings'。这一章先把落点定下来。
2.1 为什么是源码编译,而不是装一个现成的
板子上的需求可以拆成两条硬约束。第一条是小版本必须对得上:requirements.txt 是从一个 3.9 环境导出的,里面有些包对解释器小版本敏感,装到系统自带的老版本上,轻则版本回退,重则编译不过,排查起来全是噪音。第二条是这份解释器要能整体搬走:现场那边不只一台机器要用,如果解释器和系统路径缠在一起,你没法把它单独打成一个包。
现成的二进制包通常满足不了第二条。它们默认往系统路径里铺,和板子上原有的 Python 混在一起,装完之后哪些文件是你的、哪些是系统的一时说不清,打包时边界也就模糊了。源码编译的 --prefix 恰好给了一个明确的边界:所有东西都在一个目录树下,打包就是压一个目录,搬走就是解压一个目录。代价是你得自己管依赖、自己管路径,出了问题没人替你兜底。
这里还有一个容易被忽略的点:源码编译出来的解释器是“相对自己找库”的。它启动时会根据自己所在的位置往上找 lib/python3.9,找到就正常跑,找不到就报错。所以前缀目录一旦定下来,就别再挪动里面的文件层级,挪一次就可能废一次。这也是我为什么坚持在 configure 阶段就把目录名定死,而不是装完再改名。
2.2 --prefix 改的是安装位置,不是编译位置
很多人对 --prefix 的误解在于,以为它指定的是“编译产物放哪”。不是。它写进 Makefile,只在 make install 那一步生效,决定的是安装后的目录根。make 阶段编译出来的 .o、可执行文件,全都还在源码目录里躺着。
完整的第一步是这样:
bash复制# 取源码包并解压,版本号要和 requirements.txt 的来源环境对齐
wget https://www.python.org/ftp/python/3.9.18/Python-3.9.18.tgz
tar zxf Python-3.9.18.tgz
cd Python-3.9.18
# 指定安装前缀:这是 make install 的目标根目录,不是源码目录
./configure --prefix=/tmp/python39V7
逐条看这几行的含义。wget 拉下来的是源码压缩包,tar zxf 解开之后会得到一个 Python-3.9.18 目录,cd 进去是因为 configure 必须在源码根目录执行。./configure --prefix=/tmp/python39V7 做三件事:探测当前 ARM 环境上的编译器、生成 Makefile、把 /tmp/python39V7 这个字符串塞进 Makefile 的安装规则里。
执行完 configure,/tmp/python39V7 这个目录大概率还不存在,这是正常的。这一步只是把“将来装到哪”记下来,真正的目录树要等 make install 才铺开。铺开之后的结构大致是 bin/(python3、pip3 这些可执行文件)、lib/python3.9/(标准库和 site-packages)、include/(头文件)。记住 lib/python3.9/ 这个路径,第五节的报错全靠它定位。
configure 的输出要逐行看,不要一路回车到底。它会把探测到的编译器、缺少的可选依赖挨个打出来,缺什么在这一步是最容易发现的。等 make 跑到一半再报缺库,你就得从头再来一遍。
2.3 前缀目录为什么放在 /tmp 下
/tmp/python39V7 这个位置不是随手选的,它对应三个考虑。
第一是不污染系统路径。板子上本来就有一套 Python 在跑系统脚本,你把新的装到 /usr/local 里,PATH 一改,系统脚本可能就跑到新解释器上去了,这种连带影响最难查。放在 /tmp 下,只要不改 PATH,它就安安静静待在那儿,谁也不会误用。
第二是多版本并存时边界清楚。目录名里带 python39,一眼能认出这是给 3.9 用的。以后要在同一块板子上再编一个别的版本,换个前缀目录就行,两者互不干扰。
第三是打包时目录边界干净。材料里的做法是 cd /tmp 之后压缩 ./python39V7/*,前缀目录本身就是包里最外层,不会有“压缩包里还套着一层源码目录”的尴尬。
代价也要说清楚:/tmp 是临时目录,系统重启或者清理策略触发时可能被清掉。所以我的习惯是 make install 跑完、验证通过之后立刻打包,把 zip 挪到别的地方存着。真在 /tmp 里放了几天再想起来打包,翻车的概率不低。
3. 从 make 到 make install:同一份源码里的三个 Python
这一步最容易犯的错,是把三个不同阶段的解释器当成同一个东西。源码目录里有一个、前缀目录里有一个、虚拟环境里还会有一个,它们的 sys.prefix 各不相同,能干的活也各不相同。分不清这三个,后面装依赖、建环境、打包,每一步都可能把包装进错的地方。
3.1 make 之后源码目录里那个 python,别拿去建虚拟环境
bash复制# 在源码目录里执行,产出的是"未安装"状态的解释器
make
# 安装到 configure 指定的前缀目录
make install
make 只负责编译,不往 /tmp/python39V7 写任何东西。跑完之后,你会在源码目录下看到一个 python 可执行文件,甚至能直接运行它、进入交互模式。这是最迷惑人的地方——它看起来完全正常。
但这个解释器是“未安装”状态的。它的 sys.prefix 指向源码目录,标准库还散在源码树的 Lib/ 下面,没有被铺成 lib/python3.9/ 的结构。你用它去 virtualenv -p,建出来的环境会把这个源码目录当成基础解释器的根。源码目录一旦被删、被移走、被打包到别的地方,这个虚拟环境立刻报废,报出来的就是材料里那段:
code复制Could not find platform independent libraries
Could not find platform dependent libraries
Consider setting $PYTHONHOME to [:]
Python path configuration:
PYTHONHOME = (not set)
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding
ModuleNotFoundError: No module named 'encodings'
这段报错的根源就是解释器找不到自己的标准库。encodings 是 Python 启动时最早加载的模块之一,它都找不到,说明 prefix 推导出来的路径是错的。所以材料里那句提醒很关键:创建虚拟环境别用 make 目录下的 python,要用 make install 之后 --prefix 下的完整解释器。
3.2 make install 之后,怎么确认装完整了
make install 干的事是把源码目录里编译好的东西,按 configure 记下的规则铺到 /tmp/python39V7 下面。跑完之后先别急着装包,做两个检查。
第一个检查是 bin/ 目录。/tmp/python39V7/bin 下应该有 python3、pip3 这些入口。缺 pip3 说明安装过程没走完,或者中间报过错被忽略了。
第二个检查是 lib/python3.9 目录。这里面应该有标准库的目录结构,其中就包括 encodings。这个检查看着多余,实际上是第五节所有报错的判据:只要 lib/python3.9/encodings 在,解释器就没理由报 No module named 'encodings';不在,说明安装没铺完整,或者你用的根本不是这个目录下的解释器。
在 ARM 上编译,make 这一步耗时跟板子的算力直接相关,慢是正常的,不要因为等太久就中断。中断之后重新 make 一般能续上,但如果你中途改过 configure 参数,就得先清理再重来。
3.3 三个解释器的路径对照
把这三个路径列在一起,后面每次要敲 python 或 pip 之前,先回来对一眼:
| 解释器位置 | 来源 | 能不能建虚拟环境 | 能不能作为打包对象 |
|---|---|---|---|
源码目录下的 ./python |
make 产物,未安装 |
不能,prefix 指向源码树 | 不能,标准库没铺开 |
/tmp/python39V7/bin/python3 |
make install 产物 |
能,这是完整解释器 | 能,--prefix 整个目录就是包 |
./virtualenvV1/bin/python3 |
virtualenv -p 创建 |
它本身就是一个环境 | 一般不用来打包分发 |
这张表的核心是一句话:只有 make install 之后的解释器才是“完整”的。判断完整不完整,不看它能不能跑起来,看它的标准库在不在自己身边。
顺带说一个习惯。我一般会在装完之后立刻用绝对路径跑一次 /tmp/python39V7/bin/python3,确认能进交互模式、能 import 标准库里的模块。这一步花不了几秒,但能把“装是装完了、其实是残的”这种情况提前拦下来。
4. requirements.txt 落到哪个 site-packages:依赖导入与虚拟环境
编译完只是把工具造出来了,真正让它变成能干活的环境,是把 requirements.txt 里的包装进去。这一步的关键不在 pip install 这条命令本身,而在你用哪个 pip。
4.1 装依赖时,pip 的绝对路径就是一切
bash复制# 用 prefix 下的 pip3,而不是系统 pip3,也不是源码目录里的 python
/tmp/python39V7/bin/pip3 install -r ./requirements.txt
pip 有一个特性:它永远把包装进“自己所属的那个解释器”的 site-packages 里。也就是说,/tmp/python39V7/bin/pip3 装出来的包,会落在 /tmp/python39V7/lib/python3.9/site-packages;而系统自带的 pip3 装出来的包,落在系统路径下,跟你刚编译的这份解释器一点关系都没有。
这就是材料里那句“切记这里 python 必须是上面 ==prefix 的路径”的实际含义。用绝对路径写 pip,等于同时锁定了两件事:包装到哪、哪个解释器将来能 import 到它。写成 pip3 install 而依赖 PATH 去找,结果取决于当前 shell 的 PATH 长什么样,换个人、换个终端都可能不一样,这种不确定性在部署环节是致命的。
-r ./requirements.txt 里的 -r 表示从文件读包列表,./ 是相对当前目录。执行前先确认自己站在 requirements.txt 所在的那个目录里,不然 pip 会报找不到文件——这个错很低级,但在连着敲了一串命令之后特别容易犯。
4.2 virtualenv -p 指向谁,环境就长在谁身上
bash复制# -p 必须指向 make install 之后的解释器
virtualenv -p /tmp/python39V7/bin/python3 ./virtualenvV1
-p 是这个命令里唯一需要动脑的参数,它指定基础解释器。指向 /tmp/python39V7/bin/python3,虚拟环境就以这份完整解释器为模板创建,标准库从它那里继承;指向源码目录里的 ./python,环境就绑在一个临时目录上;不写 -p,默认用系统 python3,那你前面编译的工作等于白做。
后面的 ./virtualenvV1 是环境目录,放在当前目录下,名字随意,但建议带版本信息。这个目录是可以整个删掉重建的,所以不用太纠结命名。
创建完之后,环境里会有一套自己的 bin/python3 和 bin/pip3。注意,这两个是虚拟环境自己的入口,和 /tmp/python39V7/bin 下的不是同一份文件,但它们背后用的是同一套标准库。理解这一点,才能理解为什么虚拟环境里的包装了、前缀目录里却没有。
4.3 激活、导入、退出的完整闭环
bash复制# 激活后,python3 和 pip3 都指向虚拟环境内部
source virtualenvV1/bin/activate
pip3 install -r ./requirements.txt
# 退出,回到系统解释器
deactivate
source .../activate 做的事情主要是改 PATH,把虚拟环境的 bin 目录提到最前面,于是后面敲的 python3、pip3 都命中环境内的版本。这时候 pip3 install -r ./requirements.txt 装的包,落进 virtualenvV1/lib/python3.9/site-packages,和前缀目录里那份是两套。deactivate 把 PATH 还原,你立刻回到系统解释器。
这里有个值得想一想的细节:材料里 requirements.txt 装了两遍,一遍进前缀目录,一遍进虚拟环境。这不是重复劳动。前缀目录那份是给打包用的——zip 出去之后,别人解压出来就能直接 import;虚拟环境那份是给本地开发调试用的——激活之后随便折腾,装坏了删掉重建就行,不影响那份干净的安装。搞清楚哪份是“要带走的”、哪份是“自己用的”,后面打包时才不会压错目录。
如果只想验证依赖装没装对,最省事的办法是用对应前缀的解释器直接 import 一个 requirements 里的包,能 import 就说明落在它自己的 site-packages 里了。用系统 python3 去验证是没有意义的,它本来就不该有这些包。
5. 排查:No module named 'encodings' 背后的路径账
这套流程里几乎所有的报错,追到根上都是同一件事:你以为自己在用 A 解释器,实际跑起来的是 B。下面四条是我在 ARM 上编译 Python 时反复遇到的,按现象、原因、解决拆开写。
5.1 现象:解释器一起来就 No module named 'encodings'
现象很直接:执行某个 python 可执行文件,还没进交互模式就崩了,报 Fatal Python error: init_fs_encoding,最后一行是 ModuleNotFoundError: No module named 'encodings'。
原因是解释器启动的第一步就是定位标准库目录。它根据可执行文件的位置往上推 sys.prefix,再拼出 lib/python3.9,去那里加载 encodings 包。源码目录下的 ./python 推出来的 prefix 是源码根,标准库还在 Lib/ 下没被铺成安装结构;把可执行文件单独复制到别处更糟,它周围根本没有 lib/python3.9。这两种情况都会让 encodings 加载失败。
解决办法只有一个方向:用 make install 之后 /tmp/python39V7/bin/python3,并且整目录搬动,不要单独复制可执行文件。如果确实需要把它放到别的位置,就整个 /tmp/python39V7 一起挪,保持 bin 和 lib 的相对关系不变。
5.2 现象:报错里反复提示 Consider setting $PYTHONHOME
现象是上面那段报错里夹着 Could not find platform independent libraries、Could not find platform dependent libraries,以及 Python path configuration: PYTHONHOME = (not set)。
这是解释器在告诉你:我自己推不出 prefix,你可以用环境变量直接告诉我。很多人到这一步会顺手 export PYTHONHOME=/tmp/python39V7,然后发现能跑了,就以为解决了。这是后悔药,不是根治。PYTHONHOME 一旦设错版本,比如把它指到另一个 Python 的目录,标准库会串版本,报出来的错更莫名其妙;而且它只对当前 shell 生效,换个终端、换个启动脚本,问题原样复现。
我的处理顺序是:先确认用的是不是 make install 后的解释器,再确认 /tmp/python39V7/lib/python3.9/encodings 在不在,两个都对还报错,才考虑 PYTHONHOME。真要用,就写进启动脚本里固定下来,别靠手敲。
5.3 现象:pip 说装成功了,目标解释器却 import 不到
现象是 pip3 install 一路 Successfully installed,回头用 /tmp/python39V7/bin/python3 去 import,照样 ModuleNotFoundError。
原因基本可以锁定:装的时候用的不是这个前缀下的 pip3。可能是 PATH 里的系统 pip3,可能是某个已激活的虚拟环境里的 pip3,也可能是 python3 -m pip 里那个 python3 指错了。包确实装成功了,只是装进了另一个 site-packages。
解决办法是把 pip 写成绝对路径,/tmp/python39V7/bin/pip3 install -r ./requirements.txt,装完立刻用同一个前缀的解释器 import 验证一次。装和验用同一份解释器,这条链就闭合了。
5.4 现象:虚拟环境里一切正常,退出来就报 ImportError
现象是 source activate 之后跑得好好的,deactivate 一执行,同样的代码立刻报模块找不到。
原因不复杂:两个环境的 site-packages 是彼此独立的两份。你在虚拟环境里装的包,只落在 virtualenvV1/lib/python3.9/site-packages,前缀目录那份没动过。退出之后用的是系统解释器或者前缀解释器,它们当然看不到。
解决办法是先想清楚这份依赖是给谁用的。要打包带走的,必须装进前缀目录;只是本地调试用的,装虚拟环境里就好;两边都要,就装两遍,这也是材料里两条 pip3 install -r 并存的原因。别指望装一次两边都能用。
6. 把代码开发工具整目录搬走:zip 打包与三步验证
编译、装依赖、建环境都跑通之后,最后一步是把这份代码开发工具变成一个能搬走的文件。材料里的做法很朴素:
bash复制cd /tmp
# 把 prefix 目录整个压进去,包里最外层就是 python39V7
zip -r python39V7.zip ./python39V7/*
先 cd /tmp 是为了让压缩包里的相对路径从 python39V7 开始,而不是从一长串绝对路径开始。-r 是递归,把子目录一并收进去,python39V7/* 说的是这个目录下的所有内容。压出来的 zip 解压之后,最外层就是 python39V7,里面的 bin、lib 相对关系原封不动——这一点是它能被直接使用的关键,前面反复强调“整目录搬动”就是为了保住这个结构。
压完别急着发出去,做三步验证。第一步,用绝对路径跑一次 /tmp/python39V7/bin/python3 -V,确认解释器本身还能启动。第二步,跑 /tmp/python39V7/bin/pip3 -V,重点不是版本号,而是它打印出来的路径是不是指向 /tmp/python39V7 下面——路径对了,说明 pip 绑定的是这份解释器。第三步,用它 import 一个 requirements.txt 里的包,能 import 就说明前面的依赖确实装进了这个前缀的 site-packages,而不是装在别处被你顺手压了个空壳。
这三步是我血泪经验换来的。早些年我压完包直接发走,对方解压出来一跑就是 No module named 'encodings',回头查了半天才发现压缩的是源码目录,不是前缀目录。从那以后我每次打完包,都强制先把 zip 解压到一个干净目录里,用里面的解释器把那三步走一遍,确认没问题再交付。多花两分钟,省掉的是来回扯皮的一整天。
如果你的场景和我一样,是给 pyspark 这类分布式执行环境准备解释器,那 zip 就是最终交付物,验证更要严格——executor 那边没有你的 shell,PATH 和 PYTHONHOME 都不作数,能依赖的只有包里那份完整的目录结构。这也是我坚持把每一份依赖都装进前缀目录、而不是图省事复用一个虚拟环境的原因。希望帮到你。
