上周刚帮同事收拾了一台“新电脑装环境”的烂摊子。他照着某篇教程写 AES 加解密第一行from Crypto.Cipher import AES就当场报错ModuleNotFoundError: No module named Crypto。接着他在搜索框里看到“装 crypto”“装 pycrypto”“装 AES”三个答案挨个试了个遍拍了一下午的键越试越乱。我过去看了一眼他pip list的输出哭笑不得三个互相打架的加密包装了一整套。今天就把这类报错一次性拆干净——包括这三个名字之间的关系、正确安装姿势以及那些“明明装了却还是报错”的隐藏原因。无论是刚入门 Python 的新手还是换电脑后重新配环境的老手这篇文章都能直接照着走。1. 拆解报错根源Crypto、pycrypto、pycryptodome 到底什么关系1.1 三个名字背后的来龙去脉Crypto.Cipher.AES这个导入路径最早是 pycrypto 库定义的。pycrypto 在 Python 早期几乎是加密方向的事实标准大量老项目、老教程都建立在它之上。问题是这个库停更太早Python 版本一往上走它的 C 扩展就开始编译报错社区里逐渐没人维护得动。后来有人把它 fork 出来继续维护这就是 pycryptodome。fork 的时候为了兼容老代码顶层目录依然叫Crypto所以从外部看安装包从 pycrypto 变成了 pycryptodome导入路径却一直保留了from Crypto.Cipher import AES。也就是说你今天装 pycryptodome写出来的代码和十年前用 pycrypto 的项目几乎一样迁移成本很低。再往后又出了 pycryptodomex顶层目录叫Cryptodome。这是为了让你能在同一个环境里同时混用两套库一个import Crypto一个import Cryptodome。日常项目里没必要同时用装其中一套就行默认选 pycryptodome。1.2 包名和导入名为什么对不上很多人第一次卡住就是没分清“安装时的包名”和“代码里的模块名”。pip install pycryptodome里的 pycryptodome 是 PyPI 上的发行名而import Crypto里的 Crypto 是源码顶层文件夹的名字。发行名是为了在包管理平台上好认模块名是为了写代码时好写两者完全可以不一样。理解了这一点你就能看懂网上那些奇怪说法了。有人说“我装了 pycrypto”那个是老的发行名有人说“我装了 Crypto”那个可能是某次手滑装出来的第三方老包还有人说“我装了 AES”那根本就不是包名。这几类答案全部指向同一个事实真正要装的是 pycryptodome真正要写的是import Crypto。1.3 先按报错类型定位问题层排查的第一步不是急着卸载重装而是看清报错文本。from Crypto.Cipher import AES最常见的三种报错分别对应完全不同的原因报错类型真正原因ModuleNotFoundError: No module named Crypto环境里压根没有安装提供 Crypto 模块的库最常见的初始状态ImportError: cannot import name AES from Crypto.Cipher装了某个同名但无关的第三方包或者 Crypto 目录结构残缺AttributeError: module Crypto.Cipher has no attribute AES同名文件/目录劫持了导入或者 pycrypto 残留导致模块状态异常看到ModuleNotFoundError就直接看第 2 章的安装流程看到后两种说明环境里已经存在一个不完整的 Crypto 模块优先跳到第 4 章做残留清理。大多数新手的报错是第一种但最浪费时间的是后两种——因为表面看“我明明装了”。2. 正确的安装姿势认准 pycryptodome另外两个坑绕开走2.1 一条命令装好顺便把 pip 升级如果你是从零开始只需要执行这一条命令python -m pip install pycryptodome我特意写python -m pip而不是直接pip因为前者保证安装到当前正在使用的 Python 解释器避免“装在 A 环境、跑在 B 环境”的错位。这个细节后面会展开讲但它值得从一开始就成为习惯。老版本 pip 在解析新版 wheel 时偶尔会有延迟或报错所以稳妥起见先升级 pip 再装包python -m pip install --upgrade pip python -m pip install pycryptodome国内网络环境如果下载慢可以换清华源python -m pip install pycryptodome -i https://pypi.tuna.tsinghua.edu.cn/simple装完不需要配置任何 PATH 或环境变量直接import就能用。注意同一时间只保留一个提供 Crypto 模块的加密库。pycrypto、pycryptodome、pycryptodomex 以及那个来路不明的 crypto 包不要交叉混装。2.2 为什么pip install crypto是个大坑网上偶尔还能刷到让你pip install crypto的答案这里先拦一下PyPI 上确实曾经有过一个叫 crypto 的老包但它是另一个与加密没什么关系的第三方项目里面根本没有Crypto.Cipher.AES这种现代密码学结构。装完之后不仅没用还会霸占Crypto这个目录名导致后续安装 pycryptodome 时发生覆盖冲突。更常见的情况是pip install crypto现在已经无法匹配到可用版本直接报错。至于pip install AES那更是在浪费时间。AES 是加密算法名称不是 PyPI 上的包名即便能装到同名项目也不是你要的东西。这些答案基本都是十年前的老帖子被翻来覆去转载的结果照着做只会把环境越搞越乱。2.3 pycryptodomex 是另一条岔路如果你在 GitHub 项目里看到from Cryptodome.Cipher import AES说明它对应的是 pycryptodomex 这个发行名。pycryptodome 和 pycryptodomex 是同一个维护者发布的同一套代码只是发行名和顶层模块名不同一个叫Crypto一个叫Cryptodome。日常选 pycryptodome 就好原因是历史资料多、踩坑案例多、遇到问题更容易搜到答案。只有在你明确需要让两套加密库共存时才考虑 pycryptodomex。还有人图省事把项目里的import Cryptodome直接改成import Crypto但其他依赖仍按 pycryptodomex 安装这种混用方式在传参时虽然大多能跑却会让依赖关系变得难以维护。看到什么导入名就装对应的发行名别自作聪明。2.4 装完怎么快速验证装完别急着跑完整业务代码先用一行命令验证导入是否正常python -c from Crypto.Cipher import AES; print(AES.block_size)如果输出16说明导入成功AES 块大小为 16 字节这是分组加密的基本单位。再进一步确认这个 Crypto 模块到底来自哪里python -c import Crypto; print(Crypto.__file__)只要输出的路径指向 site-packages 目录而不是你项目里某个可疑的crypto.py那安装环节就完全过关了。3. “明明装了还是报错”你的 pip 和 python 可能活在两个世界3.1 环境错位的经典事故装完库仍然报ModuleNotFoundError十有八九是环境错位。举个最典型的场景你终端里敲的python是系统自带的/usr/bin/python但pip指向 Anaconda 的 base 环境或者 IDE 里选中了一个独立的 venv。每个 Python 环境都有自己独立的 site-packages 目录list 互不相通A 环境安装的 pycryptodomeB 环境当然 import 不到。这种情况在 Windows 上尤其隐蔽命令行窗口前面挂着一个(base)标识看起来环境“激活了”但编辑器里选的解释器却是另一个虚拟环境。两边的包列表永远对不上于是“装了”和“能跑”就成了两件事。3.2 三行命令看清当前环境要确认你和包是否活在同一个世界按顺序跑这三条命令python -c import sys; print(sys.executable) python -m pip --version python -m pip list | grep -i cryptWindows 没有grep就换成python -m pip list | findstr -i crypt第一条告诉你当前python解释器的完整路径第二条告诉你 pip 属于哪个 Python 环境第三条直接列出当前环境中所有名字带 crypt 的包。如果前两条命令输出的路径是同一个解释器而第三条里没有 pycryptodome那就是没装到这个环境里。**在哪运行代码就在哪装包。**这句话值得刻在桌面上。3.3python -m pip是避免错位的万能钥匙裸pip本质是一个脚本文件它可能会被 PATH 里排在前面的某个 Python 环境绑定但python -m pip是由你当前指定的解释器去执行天然就属于同一个环境。所以在排查环境问题时统一用python -m pip来安装、卸载和查看包能直接避掉一大半环境错位问题。这也是我在文章开头强调安装命令要用python -m pip的原因。很多人长期分不清pip和python -m pip的区别直到某天代码和终端里敲的命令不在一个环境才开始理解这条规则的价值。3.4 同名文件劫持一个容易被忽略的进阶坑环境错位是新手常踩的坑同名文件劫持则是进阶坑。你在项目目录里新建过crypto.py或者Crypto.py吗Python 查找模块时当前项目目录的优先级最高。Windows 和 macOS 的文件系统默认不区分大小写crypto.py和Crypto.py会被当成同一个文件。如果你在项目里写了一个只有几行调试代码的crypto.py那import Crypto时 Python 可能先找到这个手写的文件里面自然没有Cipher子模块于是报出各种奇怪的AttributeError。我遇到过一位学员他为了调试顺手在项目根目录建了个crypto.py结果from Crypto.Cipher import AES一直报错。他重装了三遍 pycryptodome 都没解决最后删掉那个只有几行代码的同名文件一切恢复。Linux 文件系统大小写敏感一般不会犯这个问题但 Windows 和 macOS 用户一定要留意。排查方法依然是打印Crypto.__file__只要路径指向项目根目录而不是 site-packages就能立刻锁定。4. 最隐蔽的坑pycrypto 残留、目录覆盖和 API 迁移4.1 一个经典的“装了等于没装”现场如果你曾经装过 pycrypto后来又按新教程安装了 pycryptodome两个包都会显示安装成功。但它们的源码解压后都指向同一个叫Crypto的顶层目录后装的那一方会覆盖先装的pip 却完全感知不到这个冲突。于是出现一种诡异状态pip show pycryptodome显示已安装import Crypto时加载的却是 pycrypto 的残余文件或者被改写得残缺不全的文件。表现就是ModuleNotFoundError: No module named Crypto.Cipher或者 AES 明明导入了却没有某些属性。同样地之前提到的来路不明 crypto 包与 pycryptodome 同时存在也会发生同类覆盖。4.2 把这些包整个清一遍再重装面对这种情况我建议直接整套卸载再来python -m pip uninstall -y crypto pycrypto pycryptodome pycryptodomex卸载之后先别急着重装用python -m pip list | grep -i cryptWindows 用 findstr确认列表里已经没有任何相关包。如果 site-packages 目录里仍然残留着一个Crypto文件夹可以用python -c import site; print(site.getsitepackages())找到包安装目录手动把这个残留文件夹清理干净然后再执行一遍安装命令。完整排查链路应该是这样的记录原始报错文本。确认当前解释器路径排除环境错位。查看当前环境中所有名字带 crypt 的包。确认Crypto.__file__的指向位置。卸载所有加密相关包。只重装 pycryptodome。重新运行导入验证命令。遇到这类问题最怕一边搜答案一边乱试命令。把链路走完十分钟就能解决乱试的话可能一下午都原地打转。4.3 从 pycrypto 老代码迁到新库会遇到什么从 pycrypto 时代迁到 pycryptodome绝大多数 AES 代码不需要改因为导入路径和主要 API 都保留了兼容性。我自己见过需要改的情况主要有两类一类是老代码使用了某个在新版中被移除或改名的内部函数另一类是依赖了 pycrypto 里比较冷门的模块。举个例子老项目里常写的Crypto.PublicKey.RSA在 pycryptodome 中也能正常使用接口基本兼容。但如果你用到了像Crypto.Cipher.XOR这类早已被淘汰的模块新库里就没有对应实现——这种东西本来也不是正经加密早该换掉了。遇到这种非常规依赖正确做法是去官方文档的 CHANGELOG 里查替代方案而不是把整个库版本往回退。退回 pycrypto在 Python 3.8 以上的环境里迎接你的将是另一场编译噩梦。5. 导入成功的下一步一段能安全落地的 AES 代码5.1 最标准的 CBC Padding 写法导入问题解决后很多人马上要在业务里用 AES。这里给一段可以直接跑的标准写法from Crypto.Cipher import AES from Crypto.Util.Padding import pad, unpad import os key os.urandom(32) # 32字节 AES-256 iv os.urandom(16) # CBC模式固定16字节 cipher AES.new(key, AES.MODE_CBC, iv) ciphertext cipher.encrypt(pad(bhello world, AES.block_size)) decipher AES.new(key, AES.MODE_CBC, iv) plaintext unpad(decipher.decrypt(ciphertext), AES.block_size) print(plaintext.decode(utf-8))这段代码里每个动作都有明确目的key随机生成 32 字节对应 AES-256 强度iv是 16 字节随机初始向量保证相同明文在不同加密过程中得到不同密文加密前用pad把明文补齐到块大小的整数倍——分组加密的铁律就是输入长度必须是分块大小倍数解密时用同一个key和同一个iv最后用unpad去掉补齐部分。CBC 模式下iv不需要保密但每次加密都应该重新生成不能写死。5.2 Key、IV 长度和数据类型的硬规则这里整理一份最容易踩的硬规则对照表参数要求常见报错关键词key只能是 16 / 24 / 32 字节Incorrect AES key lengthivCBC/CFB/OFB 等固定 16 字节IV must be 16 bytes long明文/密文必须是 bytes不是 strcant concat str to bytespadding加密前 pad解密后 unpadPadding is incorrect新手最容易踩的不是 import而是把普通字符串直接传给 AES。写cipher.encrypt(hello)会报TypeError因为 AES 只接受 bytes。正确做法是hello.encode(utf-8)。另外解密时出现Padding is incorrect通常意味着 key 或 iv 和解密的数据不匹配也可能是同一份密文被错误地复制过。5.3 生产环境更推荐 GCM 认证加密CBC 模式只加密数据不防篡改。如果密文在传输过程中被恶意改动解密端往往只能看到一个乱码或者干脆在 unpad 阶段抛异常但无法确认数据是否被完整保护。生产环境里我更推荐 GCM它属于认证加密同时保证机密性和完整性from Crypto.Cipher import AES import os key os.urandom(32) nonce os.urandom(16) cipher AES.new(key, AES.MODE_GCM, noncenonce) ciphertext, tag cipher.encrypt_and_digest(bhello) decipher AES.new(key, AES.MODE_GCM, noncenonce) plaintext decipher.decrypt_and_verify(ciphertext, tag) print(plaintext.decode(utf-8))decrypt_and_verify在 tag 校验失败时会主动抛ValueError这正是我们需要的安全行为。密文、tag、nonce 三者加一起才算完整的加密结果。实际项目里nonce 不能复用每次加密都要新生成否则会直接破坏 GCM 的安全性——很多真实泄露案例的问题就出在 nonce 被重复使用。5.4 顺便泼一盆冷水别用 ECB 模式网上很多老教程喜欢用AES.MODE_ECB因为它最简单连 iv 都不用处理。但 ECB 模式下相同明文块会生成相同的密文块明文内部的统计结构会直接暴露在密文中。十几年前的加密漏洞案例里ECB 的图案泄露问题比比皆是。教学演示可以真实项目别用。至少用 CBC预算允许就用 GCM。这个选择对代码量影响很小但对安全性影响极大。最后分享一个我自己的土办法每次换新电脑、新环境装完加密库我会先在项目根目录跑一遍python -c from Crypto.Cipher import AES; print(AES.block_size)确认输出 16再开始写业务代码。这一步顺手把导入、环境和安装三个问题一起验证了。以后再遇到from Crypto.Cipher import AES报错别急着把安装命令刷屏按顺序做完环境定位和残留清理这个报错其实非常老实它只是把最常见的三层问题压缩成了一行提示。我踩过几轮之后现在基本五分钟定位完。希望这次整理能帮你把那五分钟也省下来。