弃用和移除¶
此页面列出了 Pillow 在过去的主要版本中被弃用或已移除的功能，并提供了替代方案。
弃用功能¶
以下是被认为已弃用的功能。在适当的情况下，将发出 DeprecationWarning。
ImageFile.raise_oserror¶
自 10.2.0 版本起弃用。
ImageFile.raise_oserror() 已被弃用，将在 Pillow 12.0.0 (2025-10-15) 中移除。该函数未记录，仅对转换编解码器 decode() 方法返回的错误代码有用，而 ImageFile 已经自动执行此操作。
IptcImageFile 辅助函数¶
自 10.2.0 版本起弃用。
函数 IptcImageFile.dump 和 IptcImageFile.i，以及常量 IptcImageFile.PAD 已被弃用，将在 Pillow 12.0.0 (2025-10-15) 中移除。这些是未记录的辅助函数，用于内部使用，因此没有替代品。它们都可以用 Python 中内置函数的一行代码来替换。
ImageCms 常量和 versions() 函数¶
自 10.3.0 版本起弃用。
ImageCms 中的许多常量和一个函数已被弃用。这包括一个基于 LittleCMS 版本 1 的标志表，该表已被一个基于 LittleCMS 2 标志的新类 ImageCms.Flags 替换。
已弃用 |
改用 |
|---|---|
|
没有替代品 |
|
|
|
|
|
|
|
没有替代品 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ImageMath eval()¶
自 10.3.0 版本起弃用。
ImageMath.eval() 已被弃用。改用 lambda_eval() 或 unsafe_eval()。
BGR;15、BGR 16 和 BGR;24¶
自 10.4.0 版本起弃用。
实验性的 BGR;15、BGR;16 和 BGR;24 模式已被弃用。
ImageCms 中的非图像模式¶
自 10.4.0 版本起弃用。
在 ImageCms 中使用非 Pillow 图像模式的输入模式和输出模式已被弃用。如果模式无法映射，则默认设置为 “L” 或 “1” 也是已弃用的。
对早于 4 的 LibTIFF 的支持¶
自 10.4.0 版本起弃用。
对早于版本 4 的 LibTIFF 的支持已被弃用。升级到更新版本的 LibTIFF。
ImageDraw.getdraw hints 参数¶
自 10.4.0 版本起弃用。
getdraw() 中的 hints 参数已被弃用。
FreeType 2.9.0¶
自 11.0.0 版本起弃用。
对 FreeType 2.9.0 的支持已被弃用，将在 Pillow 12.0.0 (2025-10-15) 中移除，届时 FreeType 2.9.1 将成为最低支持版本。
我们建议升级到至少 FreeType 2.10.4，它修复了 FreeType 2.6 中引入的一个严重漏洞 (CVE 2020-15999).
ICNS (宽度、高度、缩放) 尺寸¶
自 11.0.0 版本起弃用。
在加载之前将 ICNS 图像大小设置为 (width, height, scale) 已被弃用。相反，可以使用 load(scale)。
Image isImageType()¶
自 11.0.0 版本起弃用。
Image.isImageType(im) 已被弃用。改用 isinstance(im, Image.Image)。
ImageMath.lambda_eval 和 ImageMath.unsafe_eval options 参数¶
自 11.0.0 版本起弃用。
lambda_eval() 和 unsafe_eval() 中的 options 参数已被弃用。可以改用一个或多个关键字参数。
JpegImageFile.huffman_ac 和 JpegImageFile.huffman_dc¶
自 11.0.0 版本起弃用。
JPEG 图像上的 huffman_ac 和 huffman_dc 字典未被使用。它们已被弃用，并将从 Pillow 12 (2025-10-15) 中移除。
特定 WebP 功能检查¶
自 11.0.0 版本起弃用。
features.check("transp_webp")、features.check("webp_mux") 和 features.check("webp_anim") 现已弃用。如果安装了 WebP 模块，它们将始终返回 True，直到它们在 Pillow 12.0.0（2025-10-15）中被删除。
获取指向对象的内部指针¶
自 11.0.0 版本起弃用。
Image.core.ImagingCore.id 和 Image.core.ImagingCore.unsafe_ptrs 现已弃用，将在 Pillow 12（2025-10-15）中删除。它们用于获取指向 ImagingCore 内部结构的原始指针。要与 C 代码交互，可以使用 Image.Image.getim()，它返回一个 Capsule 对象。
已删除的功能¶
已弃用的功能仅在经过适当的弃用期后，才在主要版本中删除。
TiffImagePlugin IFD_LEGACY_API¶
在 11.0.0 版中删除。
TiffImagePlugin.IFD_LEGACY_API 已被删除，因为它是一个未使用的设置。
PSFile¶
自 9.5.0 版起已弃用。
在 11.0.0 版中删除。
PSFile 类已在 Pillow 11（2024-10-15）中删除。此类仅用作内部使用的帮助程序，因此没有替代品。如果您需要此功能，它是一个非常短的类，可以轻松地用您自己的代码重新创建。
PyAccess 和 Image.USE_CFFI_ACCESS¶
自 10.0.0 版起已弃用。
在 11.0.0 版中删除。
由于 Pillow 的 C API 现在比 PyPy 上的 PyAccess 更快，因此 PyAccess 已被删除。Pillow 的 C API 现在将在 PyPy 上使用。
Image.USE_CFFI_ACCESS（用于从 C API 切换到 PyAccess）也已被删除。
Tk/Tcl 8.4¶
自 8.2.0 版起已弃用。
在 10.0.0 版中删除。
Pillow 10.0.0（2023-07-01）中删除了对 Tk/Tcl 8.4 的支持。
类别¶
自 8.2.0 版起已弃用。
在 10.0.0 版中删除。
im.category 已与相关的 Image.NORMAL、Image.SEQUENCE 和 Image.CONTAINER 属性一起删除。
要确定图像是否包含多个帧，可以使用 getattr(im, "is_animated", False) 代替。
JpegImagePlugin.convert_dict_qtables¶
自 8.3.0 版起已弃用。
在 10.0.0 版中删除。
自 Pillow 8.3.0 弃用以来，convert_dict_qtables 方法不再对给定的数据执行任何操作，并且已被删除。
ImagePalette 大小参数¶
自 8.4.0 版起已弃用。
在 10.0.0 版中删除。
在 Pillow 8.3.0 之前，ImagePalette 默认情况下需要特定长度的调色板数据，并且可以使用 size 参数来覆盖它。Pillow 8.3.0 删除了默认的所需长度，也删除了对 size 参数的需求。
ImageShow.Viewer.show_file 文件参数¶
自 9.1.0 版起已弃用。
在 10.0.0 版中删除。
show_file() 中的 file 参数已被删除，并由 path 替换。
实际上，viewer.show_file("test.jpg") 将继续工作不变。
常量¶
自 9.1.0 版起已弃用。
在 10.0.0 版中删除。
许多常量已被删除。相反，添加了 enum.IntEnum 类。
注意
Pillow 9.1.0 中已弃用其他 Image 常量，但这在 Pillow 9.4.0 中被撤消，这些常量现在将保持可用。参见 常量
已删除 |
改用 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FitsStubImagePlugin¶
自 9.1.0 版起已弃用。
在 10.0.0 版中删除。
已删除存根图像插件 FitsStubImagePlugin。FITS 图像可以通过 FitsImagePlugin 在没有处理程序的情况下读取。
字体大小和偏移方法¶
自 9.2.0 版起已弃用。
在 10.0.0 版中删除。
已删除几个用于计算渲染文本大小和偏移的函数
已删除 |
改用 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
以前的代码
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
width, height = font.getsize("Hello world")
left, top = font.getoffset("Hello world")
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
width, height = draw.textsize("Hello world", font)
width, height = font.getsize_multiline("Hello\nworld")
width, height = draw.multiline_textsize("Hello\nworld", font)
改用
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
left, top, right, bottom = font.getbbox("Hello world")
width, height = right - left, bottom - top
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
width = draw.textlength("Hello world", font)
left, top, right, bottom = draw.multiline_textbbox((0, 0), "Hello\nworld", font)
width, height = right - left, bottom - top
以前，size 方法返回一个 height，其中包含文本的垂直偏移量，而新的 bbox 方法将此区分成 top 偏移量。
如果您使用这些方法来对齐文本，请考虑使用 文本锚点，它可以避免在非英语文本或不寻常的字体中可能出现的问题。例如，而不是以下代码
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
width, height = draw.textsize("Hello world", font)
x, y = (100 - width) / 2, (100 - height) / 2
draw.text((x, y), "Hello world", font=font)
改用
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("Tests/fonts/FreeMono.ttf")
im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)
draw.text((100 / 2, 100 / 2), "Hello world", font=font, anchor="mm")
FreeTypeFont.getmask2 fill 参数¶
自 9.2.0 版起已弃用。
在 10.0.0 版中删除。
已删除 FreeTypeFont.getmask2() 的未记录参数 fill。
PhotoImage.paste box 参数¶
自 9.2.0 版起已弃用。
在 10.0.0 版中删除。
box 参数未使用，已被删除。
PyQt5 和 PySide2¶
自 9.2.0 版起已弃用。
在 10.0.0 版中删除。
Qt 5 已于 2020-12-08 对开源用户达到使用寿命终结 (EOL) （对于商业许可证持有者，将在 2023-12-08 达到 EOL）。
Image.coerce_e¶
自 9.2.0 版起已弃用。
在 10.0.0 版中删除。
此未记录方法已被删除。
PILLOW_VERSION 常量¶
自 5.2.0 版起已弃用。
在 9.0.0 版中删除。
请改用 __version__。
它最初是在 Pillow 7.0.0 中删除的，但在 7.1.0 中暂时恢复，以便为项目提供更多升级时间。
Image.show 命令参数¶
从 7.2.0 版本开始弃用。
在 9.0.0 版中删除。
已删除 command 参数。请改用 ImageShow.Viewer 的子类。
Image._showxv¶
从 7.2.0 版本开始弃用。
在 9.0.0 版中删除。
请改用 Image.Image.show()。如果需要自定义行为，请使用 ImageShow.register() 添加自定义的 ImageShow.Viewer 类。
ImageFile.raise_ioerror¶
从 7.2.0 版本开始弃用。
在 9.0.0 版中删除。
在 Python 3.3 中，IOError 已合并到 OSError 中。因此，已删除 ImageFile.raise_ioerror。请改用 ImageFile.raise_oserror。
FreeType 2.7¶
从 8.1.0 版本开始弃用。
在 9.0.0 版中删除。
已删除对 FreeType 2.7 的支持。
我们建议升级到至少 FreeType 2.10.4，该版本修复了 FreeType 2.6 中引入的一个严重漏洞 (CVE 2020-15999)。
im.offset¶
从 1.1.2 版本开始弃用。
在 8.0.0 版本中已删除。
im.offset() 已被删除，请改用 ImageChops.offset()。
它在 PIL 1.1.2 中被标记为弃用，从 1.1.5 开始发出 DeprecationWarning，从 Pillow 3.0.0 开始发出 Exception，从 3.3.0 开始发出 NotImplementedError。
Image.fromstring、im.fromstring 和 im.tostring¶
从 2.0.0 版本开始弃用。
在 8.0.0 版本中已删除。
Image.fromstring()已被删除，请改用Image.frombytes()。im.fromstring()已被删除，请改用frombytes()。im.tostring()已被删除，请改用tobytes()。
它们从 2.0.0 开始发出 DeprecationWarning，从 3.0.0 开始发出 Exception，从 3.3.0 开始发出 NotImplementedError。
ImageCms.CmsProfile 属性¶
从 3.2.0 版本开始弃用。
在 8.0.0 版本中已删除。
已删除 PIL.ImageCms.core.CmsProfile 中的一些属性。从 6.0.0 开始，它们发出 DeprecationWarning
已删除 |
改用 |
|---|---|
|
填充了 |
|
填充了 |
|
Unicode |
|
Unicode |
|
Unicode |
|
Unicode |
|
Unicode |
Python 2.7¶
从 6.0.0 版本开始弃用。
在 7.0.0 版本中已删除。
Python 2.7 于 2020 年 1 月 1 日停止支持。Pillow 6.x 是最后一个支持 Python 2 的系列。
Image.__del__¶
从 6.1.0 版本开始弃用。
在 7.0.0 版本中已删除。
已删除 Image.__del__ 中隐式关闭图像底层文件的操作。请改用上下文管理器或调用 Image.close() 以确定性方式关闭文件。
以前的方法
im = Image.open("hopper.png")
im.save("out.jpg")
改用
with Image.open("hopper.png") as im:
im.save("out.jpg")
PIL.*ImagePlugin.__version__ 属性¶
从 6.0.0 版本开始弃用。
在 7.0.0 版本中已删除。
已删除各个插件的版本常量。请改用 PIL.__version__。
已删除 |
已删除 |
已删除 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PyQt4 和 PySide¶
从 6.0.0 版本开始弃用。
在 7.0.0 版本中已删除。
Qt 4 于 2015 年 12 月 19 日停止支持。其 Python 绑定也已停止支持：PyQt4 自 2018 年 8 月 31 日起停止支持，PySide 自 2015 年 10 月 14 日起停止支持。
已从 ImageQt 中删除对 PyQt4 和 PySide 的支持。请升级到 PyQt5 或 PySide2。
设置 TIFF 图像的大小¶
从 5.3.0 版本开始弃用。
在 7.0.0 版本中已删除。
直接设置 TIFF 图像的大小（例如 im.size = (256, 256)）会抛出错误。请改用 Image.resize。
VERSION 常量¶
自 5.2.0 版起已弃用。
在 6.0.0 版本中已删除。
VERSION（旧的 PIL 版本，始终为 1.1.7）已删除。请改用 __version__。
未记录的 ImageOps 函数¶
从 4.3.0 版本开始弃用。
在 6.0.0 版本中已删除。
已删除 ImageOps 中几个未记录的函数。请改用 ImageFilter 中的等效函数。
已删除 |
改用 |
|---|---|
|
|
|
|
|
|
|
|
|
|
PIL.OleFileIO¶
从 4.0.0 版本开始弃用。
在 6.0.0 版本中已删除。
PIL.OleFileIO 在 Pillow 4.0.0（2017 年 1 月）中被删除，原因是它采用的是上游 olefile Python 包，并在 5.0.0（2018 年 1 月）中被替换为 ImportError。现在已从 Pillow 中删除了弃用的文件。如果需要，请从 PyPI 安装（例如，python3 -m pip install olefile）。
import _imaging¶
在 2.1.0 版本中已删除。
Pillow >= 2.1.0 不再支持 import _imaging。请改用 from PIL.Image import core as _imaging。
Pillow 和 PIL¶
在 1.0.0 版本中已删除。
Pillow 和 PIL 不能在同一环境中共存。在安装 Pillow 之前，请先卸载 PIL。
import Image¶
在 1.0.0 版本中已删除。
Pillow >= 1.0 不再支持 import Image。请改用 from PIL import Image。