手头攒了一批图尺寸参差不齐有的手机直出三千多像素宽有的截图只有几百文件名还夹着空格和中文括号。这种活儿交给带界面的软件一张张改改到第十张就想砸键盘。我第一次认真用 Pillow 就是为了干这件事写几十行脚本把整个文件夹的图统一压到 1200 像素宽顺手补个白边几分钟跑完。Pillow 是 Python 生态里最常用的图像处理库前身是 PIL负责打开、转换、缩放、裁剪、合成、绘制这些基础但高频的操作几乎所有做爬虫存图、批量修图、生成报表配图、给模型做预处理的场景都绕不开它。适合完全没接触过图像处理的新手也适合用了很久但只会resize和save的人——后者往往踩的坑更多因为基础 API 太顺手反而忽略了背后的模式、插值和元数据。1. Image.open 之后你拿到的东西比想象中懒1.1 文件句柄会被一直捏着不放很多人对Image.open()的第一印象是读文件跟内置的open()一样读完拉倒。这个理解会带来很隐蔽的问题。Pillow 的open()其实只读文件头把尺寸、格式、颜色模式、元数据这些信息登记到Image对象里真正的像素数据要等第一次用到才解码。这个设计对批量处理是好事但也意味着文件句柄一直开着直到对象被回收或者你显式调用close()。在 Linux 上处理几万张图如果不关句柄跑着跑着就会撞上Too many open files。我第一次遇到时排查了半天还以为是路径写错了。后来改成with写法from PIL import Image with Image.open(input.jpg) as img: print(img.size, img.mode, img.format) img.load() # 强制解码之后的操作用的是内存里的数据 data img.copy() # 复制一份脱离原文件load()是显式触发解码的方法调用之后文件句柄可以被释放。copy()则是把已经解码的数据独立出来后续对data做任何变换都跟磁盘上那张图没关系了。如果你想把图存到别的地方再处理复制一份是稳妥的做法。1.2 size、format、mode 三个属性划定操作边界打开一张图之后先别急着动手把三个属性看一遍能省掉后面大半的调试时间。属性含义常见取值用途size像素宽高元组(1920, 1080)计算缩放比例、分配画布format磁盘上的文件格式JPEG、PNG、WEBP、GIF决定保存时能带哪些参数mode像素的颜色模式RGB、RGBA、L、P、CMYK决定能不能直接做像素运算size的顺序是宽在前、高在后跟numpy数组的shape正好反过来这点在跟别的库混用时特别容易写反。format只有从磁盘打开才有值用Image.new()新建的图format是None保存时才由扩展名决定。mode是最容易被忽略的一个后面单独说。另外几个顺手的字段img.filename记录来源路径img.info是个字典装着 EXIF、DPI、ICC 配置这些杂项img.getbands()返回通道名元组img.getextrema()返回每个通道的最小最大值判断一张图是不是纯白或者全黑用getextrema()比逐像素遍历快得多。1.3 一段能直接跑的最小骨架把上面这些串起来一个够用的单图处理骨架大概长这样from pathlib import Path from PIL import Image def normalize(src: Path, dst: Path, target_width: int 1200) - None: with Image.open(src) as img: img.load() if img.width target_width: ratio target_width / img.width new_size (target_width, round(img.height * ratio)) img img.resize(new_size, Image.Resampling.LANCZOS) if img.mode not in (RGB, L): img img.convert(RGB) img.save(dst, optimizeTrue)这段代码里有两个细节值得说。一是resize只在原图比目标宽时才执行避免把小图放大变糊二是convert(RGB)放在缩放之后因为缩放在 RGB 三通道上的计算量比 RGBA 四通道小序列上的微小优化在批量处理时能省下可观的时间。另外Pillow 从 9.1 开始把重采样常量挪到了Image.Resampling命名空间下10.0 版本直接删掉了Image.ANTIALIAS、Image.LANCZOS这些旧别名。老代码迁到新版本会直接报AttributeError这是升级时最高频的问题之一。2. 颜色模式没搞对后面每一步都在还债2.1 RGB、RGBA、L、P 到底差在哪很多人对颜色模式的理解停留在有的图带透明有的不带但实际差异比这细得多。RGB是三通道每通道 8 位共 24 位色绝大多数 JPEG 都是这个模式。RGBA多一个 alpha 通道记录透明度PNG 常见。L是单通道灰度每像素一个 0 到 255 的值文件小、计算快做边缘检测、二值化、OCR 预处理时经常主动转过去。P是调色板模式每个像素存的是索引索引指向调色板里的 256 种颜色GIF 和部分 PNG 用这个模式省空间。坑主要在P上。带透明的 PNG 有时候是P模式透明度藏在info[transparency]里而不是一个独立的通道。这时候直接convert(RGB)透明区域会变成调色板里的某个颜色经常是黑色或者一团杂色。正确做法是先转RGBAif img.mode P: img img.convert(RGBA)转完再判断 alpha 通道是否全 255如果全不透明再降回RGB也不迟。CMYK是印刷用四色模式某些印刷厂给的素材就是它Pillow 能读能转但转RGB时颜色会有偏差因为 Pillow 内部没有完整色彩管理只是简单换算。如果颜色要求严格得借助 ICC 配置文件处理这已经不是简单使用的范畴了。2.2 透明底 PNG 存成 JPEG 变黑的真正原因这个现象太经典了。透明区域的像素在RGBA里通常是(0, 0, 0, 0)也就是 RGB 值是黑的只是被 alpha 设成完全透明看不见。一旦丢弃 alpha 通道变成RGB那个黑色就露出来了。解决办法不是简单改个模式而是主动铺一层底色def flatten_to_white(img: Image.Image) - Image.Image: if img.mode in (RGBA, LA, P): rgba img.convert(RGBA) canvas Image.new(RGB, rgba.size, (255, 255, 255)) canvas.paste(rgba, maskrgba.split()[3]) return canvas return img.convert(RGB)rgba.split()[3]取的是 alpha 通道作为paste的蒙版这样只有不透明的部分被贴上去透明部分保留白底。这个思路可以推广到任何底色电商图的白底、设计稿的灰底都是这么做的。2.3 哪些转换是单向的模式转换里有一条不太直观的规则从高信息量往低信息量转是不可逆的。RGB转L之后原来的颜色信息就没了再转回RGB只会得到三个通道值相同的灰度图看起来像是褪了色。所以流程设计上灰度化这种操作应该放在最后一步别在中间环节做。我曾经在一个批处理脚本里图省事一开始就把所有图转成L加速后续运算结果后面要做彩色文字水印时发现底色全灰只能整个流程重写。反过来的情况也存在。L转RGB虽然视觉上没变化但内存占用翻三倍处理几万张图时是实打实的负担。能不转就不转除非下游 API 明确要求。3. 缩放裁剪旋转参数背后的取舍逻辑3.1 resize 和 thumbnail 的选择题两个方法都在缩图行为完全不同混用会出问题。resize((w, h))强制输出指定尺寸不管原图宽高比直接拉伸容易变形。thumbnail((w, h))是原地修改保持宽高比只在目标框内等比缩小而且不会放大超过原图。注意它是原地操作返回值是Noneimg Image.open(a.jpg) img.thumbnail((800, 800)) # 正确 # img img.thumbnail((800, 800)) # 错误img 会变成 None这个None返回值坑过无数人包括我。线程里跑一堆任务某个缩图函数返回了None传给下游报错堆栈指向几十行之外查起来很费劲。选哪个看需求。做缩略图、列表页展示图用thumbnail快且不会破坏比例。做固定尺寸的头像、封面、模型输入用resize但要自己算好裁剪区域不然人像会被拉成宽脸。3.2 六种插值方式的实测差别Pillow 支持六种重采样方式效果和速度差别不小。常量适用场景速度效果NEAREST像素画、标签图、掩码图最快有锯齿不产生新颜色BOX大幅缩小快平均池化略糊BILINEAR一般缩小中平滑但有细节损失HAMMING介于双线性与双三次之间中折中方案BICUBIC放大慢锐度好可能有轻微振铃LANCZOS缩小首选慢锐度高边缘干净缩小图片默认用LANCZOS基本不会错。放大图片我一般用BICUBICLANCZOS在放大时容易在强边缘出现轻微过冲看着像描了边。做二值掩码或者标签图必须用NEAREST否则插值会生成 128 这种中间值标签语义就毁了。有个现实中的加速技巧JPEG 解码时可以用draft让解码器直接按比例降采样比完整解码后再缩小快得多with Image.open(big.jpg) as img: img.draft(RGB, (1200, 1200)) img img.resize((1200, round(img.height * 1200 / img.width)), Image.Resampling.LANCZOS)draft只对 JPEG 有效它会告诉解码器按 1/2、1/4、1/8 的比例出图。处理几千像素宽的手机原图时解码时间能砍掉一大半代价是损失一点点锐度视觉上基本看不出来。3.3 crop、ImageOps.fit、ImageOps.pad 的分工crop((left, upper, right, lower))是最原始的方式坐标为左上闭、右下开需要自己算中心区域。稍微方便一点的是ImageOps.fit给定目标尺寸它会自动从中心裁一块再缩放到目标大小适合做封面from PIL import ImageOps cover ImageOps.fit(img, (800, 450), methodImage.Resampling.LANCZOS)ImageOps.pad走的是另一条路保持完整内容不足的部分用指定颜色填充适合做需要留白的产品图padded ImageOps.pad(img, (800, 800), color(255, 255, 255), centering(0.5, 0.5))这两个函数内部都处理了宽高比和边界的判断比自己算crop的坐标可靠得多。手写crop最常见的错误是把right和lower当成闭区间结果裁出来的图少一像素拼图时出现一像素的缝。3.4 旋转与翻转的 expand 参数rotate(angle)默认逆时针旋转关键在expand。默认expandFalse转 45 度之后四个角会被切掉。设成True画布会自动扩展到能装下整张旋转后的图多出来的部分用黑色填充rotated img.rotate(45, expandTrue, resampleImage.Resampling.BICUBIC, fillcolor(255, 255, 255))fillcolor参数是常被忽略的一个不指定的话新扩展出来的区域是纯黑在白底场景里特别突兀。90 度整数倍的旋转和翻转不要用rotate用transpose更快也更精确rot90 img.transpose(Image.Transpose.ROTATE_90) flipped img.transpose(Image.Transpose.FLIP_LEFT_RIGHT)transpose是纯像素重排没有插值不会有任何模糊。Pillow 9.1 之后这些常量都在Image.Transpose下面老版本直接挂在Image上迁移时注意对照。4. 保存这一步最容易把前面的活干废4.1 JPEG 的 quality 区间怎么定save()的默认行为对 JPEG 是quality75大部分人不知道这件事直接存完发现画质下降还以为是前面的缩放导致的。quality 的取值是 1 到 95超过 95 的部分提升极小但文件体积增长明显。实测下来75 到 85 是体积和画质的平衡区展示用图 85 足够缩略图 70 都能接受需要二次编辑的中间文件才上 92 到 95。几个配套参数值得一起用img.save(out.jpg, quality85, optimizeTrue, progressiveTrue, subsampling0)optimizeTrue会让编码器尝试更优的霍夫曼表体积能再降几个百分点代价是编码稍慢。progressiveTrue生成渐进式 JPEG网络加载时先出模糊轮廓再逐层清晰网页首屏体验会好一些。subsampling0关闭色度抽样保留完整的色彩分辨率文字边缘和纯色块边界会干净很多代价是体积涨 10% 到 20%。做带文字的海报或者截图这个参数值得打开。4.2 手机照片躺着的根源在 EXIF手机拍摄时传感器方向是固定的机身旋转的信息记在 EXIF 的Orientation标签里看图软件会读这个标签自动转正。Pillow 不会自动处理它老老实实按存储的像素顺序给你所以你看到的是躺着或者倒着的图。修法很简单一行搞定from PIL import ImageOps with Image.open(phone.jpg) as img: fixed ImageOps.exif_transpose(img) fixed.save(fixed.jpg, quality88)exif_transpose读取 Orientation 标签按需做翻转或旋转然后把这个标签重置为正常值避免二次处理时又被转一次。这里有个容易忽略的连带问题经过resize、crop之后exif_transpose可能已经失效因为某些操作会丢掉info里的 EXIF 数据。稳妥的顺序是在open()之后第一件事就做exif_transpose再做其他变换。另外如果你希望保留拍摄时间、相机型号这些信息保存时要把 EXIF 传回去exif fixed.info.get(exif) fixed.save(out.jpg, exifexif, quality88)不传的话输出文件就是一张干干净净、没有任何元数据的新图做照片归档时这个细节很重要。4.3 PNG 和 WEBP 的参数不是同一套JPEG 的quality参数在 PNG 上没有意义PNG 是无损格式控制体积靠的是压缩级别img.save(out.png, optimizeTrue, compress_level9)compress_level取值 0 到 9默认 6。9 的压缩率最高、耗时最长批量处理大批 PNG 时从 6 提到 9耗时可能翻倍而体积只降 3%性价比不高。除非是最终交付物一般保持默认就够了。WEBP 是另一套参数体系它同时支持有损和无损img.save(out.webp, quality80, method6) # 有损 img.save(out.webp, losslessTrue, method6) # 无损method控制编码 effort0 到 6越高越慢越小。WebP 在同画质下通常比 JPEG 小 25% 到 35%代价是兼容性稍差一些老系统上可能打不开。还有一个隐蔽的坑保存格式由扩展名或者显式format参数决定两个都不给会抛ValueError: unknown file extension。从 BytesIO 读写时尤其要注意显式指定format。5. 批量处理脚本的骨架我改过三版才顺手5.1 输出路径与命名规则先想清楚批处理脚本写到第二版你会发现真正麻烦的不是图像操作而是路径管理。输入目录可能是嵌套的输出要不要保持同样的层级同名文件怎么处理中途失败重跑会不会覆盖已经处理好的结果我的做法是先定一套规则再写代码输出目录结构与输入保持一致用Path.relative_to()算相对路径文件名保持原名只换扩展名已存在的输出默认跳过加--force才覆盖。这样中断之后重跑是幂等的不用担心重复劳动。from pathlib import Path def iter_images(root: Path): exts {.jpg, .jpeg, .png, .webp, .bmp} for p in root.rglob(*): if p.is_file() and p.suffix.lower() in exts: yield p def target_path(src: Path, src_root: Path, dst_root: Path, new_ext: str) - Path: rel src.relative_to(src_root) return dst_root / rel.with_suffix(new_ext)用rglob遍历比手写递归省事suffix.lower()处理大写扩展名这两个细节不做的话遇到.JPG或者.PNG就会漏文件而且是静默漏掉跑完了才发现少了几十张。5.2 异常要精确捕获到 UnidentifiedImageError坏图是批处理的家常便饭。下载中断留下半截文件、扩展名写着 jpg 实际是网页、伪装成图片的文本文件这些都会让Image.open()抛异常。全部except Exception兜住虽然不会崩但出了问题完全没法定位。Pillow 从 7.0 开始提供了专门的UnidentifiedImageError读取阶段的问题基本都能用它捕获from PIL import UnidentifiedImageError try: with Image.open(p) as img: img.load() process(img) except UnidentifiedImageError: log.warning(无法识别%s, p) except OSError as e: log.warning(读取失败%s - %s, p, e)OSError覆盖的是文件被占用、权限不足、磁盘坏道这类 IO 问题。两类分开捕获日志里就能直接看出是文件本身坏了还是环境问题。还有一个更隐蔽的情况有些 JPEG 文件头正常、能打开但数据在中间被截断load()时才报OSError: image file is truncated。Pillow 默认容忍一定程度的截断如果确实想强行读可以设ImageFile.LOAD_TRUNCATED_IMAGES True但读出来的图下半部分可能是灰的或者错的要不要这么干取决于业务能不能接受。5.3 内存和耗时才是真瓶颈单张图的处理时间是毫秒级批量之后瓶颈立刻转移到 IO 和内存上。三个经验第一用ThreadPoolExecutor做并发。图像编解码大部分工作在 C 层会释放 GIL多线程确实能提速实测四线程处理几千张图比单线程快两倍多。但如果后续操作里有大量 Python 层循环比如逐像素判断多线程就没用了得换多进程。第二别一次性把所有图读进内存。有次我为了排序方便先把整个目录的图都open了然后内存直接飙到几个 G机器开始换页比不并发还慢。正确做法是边遍历边处理边释放。第三进度输出不要用print每次都刷。几千个文件跑起来控制台刷屏本身就要花时间。用tqdm或者每 100 个打一行体感差别很明显。for i, p in enumerate(paths, 1): handle(p) if i % 100 0: print(f{i}/{len(paths)})顺带说一句超大图比如扫描件动辄一两万像素宽处理时先thumbnail降采样再做其他处理内存占用能降一个数量级。resize是直接分配目标尺寸的缓冲区但输入图本身还是完整解压在内存里的一张 20000×20000 的 RGB 图光像素数据就是 1.2 GB。6. 加水印和套滤镜Pillow 的另一半能力6.1 ImageDraw 画字与字体加载给图上加文字水印靠的是ImageDraw和ImageFontfrom PIL import ImageDraw, ImageFont font ImageFont.truetype(/path/to/NotoSansCJK-Regular.ttc, 36) draw ImageDraw.Draw(img) draw.text((20, 20), 示例水印, fontfont, fill(255, 255, 255), anchorlt)字体加载是最容易卡住的一步。ImageFont.truetype()需要字体文件的绝对路径不能只给字体名。Pillow 自带的load_default()用的是位图字体不支持中文也不支持缩放Pillow 10.1 之后才支持传size参数但字形依然很有限。所以中文场景必须自己找 TTF 或 TTC 文件。获取字体文件路径有个跨平台的小技巧用matplotlib里的字体索引虽然有点重但省事from matplotlib import font_manager path font_manager.findfont(Noto Sans CJK SC)不想引入额外依赖的话就得按系统去找。Linux 上一般在/usr/share/fonts/下按子目录找macOS 在/System/Library/Fonts/Windows 在系统盘的字体目录里。找不到文件时truetype会抛OSError: cannot open resource这个报错指向性很明确基本就是路径错了或者权限不够。新版 Pillow 还删掉了ImageDraw.textsize()改用textbbox()或者textlength()来测量文字尺寸。想把水印放到右下角对齐必须用textbbox算宽高老代码里的textsize会直接报AttributeError这是版本迁移的高频报错。6.2 ImageFilter 里真正好用的几个滤镜这些年用得越来越多尤其是给图片做高斯模糊当背景。ImageFilter里常用的其实就那几个滤镜参数典型用途GaussianBlurradius背景虚化、脱敏BoxBlurradius快速模糊质量一般UnsharpMaskradius、percent、threshold锐化比SHARPEN可控MedianFiltersize去噪点处理扫描件FIND_EDGES无快速边缘提取GaussianBlur的radius是模糊半径3 到 5 适合做毛玻璃背景20 以上基本看不出原图内容脱敏场景常用。代价是半径越大越慢做背景虚化时我一般先把图缩到 1/4 再模糊最后放大回来速度快几十倍而视觉效果几乎无差。UnsharpMask的percent控制锐化强度threshold是触发锐化的最小差异设成 2 到 3 可以避免在纯色区域噪点被放大。比直接套ImageFilter.SHARPEN精细得多后者在深色区域很容易糊成一片。6.3 用蒙版做半透明合成水印不想太扎眼直接让整张水印图带透明度靠的是 alpha 通道加pastewatermark Image.open(logo.png).convert(RGBA) alpha watermark.split()[3].point(lambda a: int(a * 0.4)) watermark.putalpha(alpha) base Image.open(photo.jpg).convert(RGBA) base.alpha_composite(watermark, (base.width - watermark.width - 20, 20)) base.convert(RGB).save(out.jpg, quality88)point()配合 lambda 做通道级别的批量运算是 Pillow 里少见的、能优雅处理逐像素需求的接口。它比写for循环快一个数量级因为它是在 C 层遍历的。paste和alpha_composite的区别在于后者做的是真正的 alpha 混合前者在有蒙版时是覆盖。做半透明叠加必须用alpha_composite用paste出来的效果是硬替换边缘会有明显的锯齿感。7. 装不上、找不到字、内存炸三类报错的排查路径7.1 import PIL 成功但 import Image 失败这个报错看着矛盾其实逻辑很清楚ModuleNotFoundError: No module named PIL说明压根没装或者装到了别的 Python 环境里。先确认解释器which python或者python -c import sys; print(sys.executable)再看pip -V指向的路径是否一致。多版本共存、虚拟环境未激活、conda 与系统 pip 混用是三大元凶。装的时候包名是pillow而不是PILpython -m pip install --upgrade pillow用python -m pip而不是裸pip能保证装到当前解释器下面避免装错地方。这个习惯能规避掉一大半的环境问题。另一个高频报错是ImportError: The _imaging extension was built for another version of Pillow or PIL这是旧版 PIL 残留导致的。清理干净再重装python -m pip uninstall pillow PIL python -m pip install pillow如果系统里还留着PIL.pth文件或者PIL目录也要手工删掉否则会一直抢占导入。还有一种情况是能装不能用报ImportError指向_imaging.cpython-xxx.so。这通常是 wheel 与 Python 版本或 CPU 架构不匹配换一个版本重装或者升级 pip 让它拿到正确的预编译包。7.2 字体文件路径这关OSError: cannot open resource出现时先确认三件事路径是绝对路径还是相对路径、文件是否存在、当前进程有没有读权限。相对路径依赖工作目录在 IDE 里跑和在脚本目录下跑结果可能不一样这是最迷惑人的一点。from pathlib import Path font_path Path(__file__).parent / assets / NotoSansCJK-Regular.ttc if not font_path.exists(): raise FileNotFoundError(font_path) font ImageFont.truetype(str(font_path), 32)用__file__定位脚本所在目录再拼相对资源路径是跨环境最稳的写法。还有一个静默的水印问题是中文变方块。用只含英文字形的字体加载中文不会报错就是一片豆腐块。判断方法很简单用font.getbbox(中)看返回的宽度是不是 0 或者负数是的话就是字体里没有这个字形。7.3 DecompressionBombWarning 与超大图处理大图时可能看到这个警告DecompressionBombWarning: Image size (100000000 pixels) exceeds limit of 89478485 pixels这是 Pillow 的防护机制防止恶意构造的超大图撑爆内存。像素数超过约 8900 万会警告超过两倍会直接抛DecompressionBombError。如果来源可信、机器内存也够可以显式调高上限Image.MAX_IMAGE_PIXELS 200_000_000但更好的做法是不碰这个开关而是从流程上避免解压完整大图先用draft降采样解码JPEG 有效或者分块读取。真的需要处理超大图Pillow 并不是最优工具pyvips这类支持流式处理的库更合适。另一个容易混淆的报错是MemoryError它跟DecompressionBomb不是一回事。前者是真的内存不够发生在解码或resize分配缓冲区时后者是 Pillow 主动拒绝执行。日志里区分清楚这两个排查方向完全不同。我在实际项目里的做法是批处理脚本开头统一设定上限同时记录每张图的尺寸跑完统计一下最大的十张如果发现明显异常的大图就单独处理不跟普通图混在一个批里。数据量上来之后这种分而治之比调参数管用得多。
