棄用與移除¶
此頁面列出 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 的旗標表，該表已被新的類別 ImageCms.Flags 取代，該類別基於 LittleCMS 2 旗標。
已棄用 |
改用 |
|---|---|
|
沒有替代方案 |
|
|
|
|
|
|
|
沒有替代方案 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 影像尺寸為 (寬度, 高度, 縮放比例) 的方式已被棄用。請改用 load(縮放比例)。
Image isImageType()¶
自 11.0.0 版本起棄用。
Image.isImageType(im) 已被棄用。請改用 isinstance(im, Image.Image)。
ImageMath.lambda_eval 和 ImageMath.unsafe_eval 選項參數¶
自 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 file 引數¶
自 9.1.0 版本起已棄用。
已在 10.0.0 版本中移除。
show_file() 中的 file 引數已被移除，並由 path 取代。
實際上，viewer.show_file("test.jpg") 將繼續不變地工作。
常數¶
自 9.1.0 版本起已棄用。
已在 10.0.0 版本中移除。
許多常數已被移除。取而代之的是，已新增 enum.IntEnum 類別。
注意
額外的 Image 常數已在 Pillow 9.1.0 中棄用，但在 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 對開源使用者達到生命週期結束 (End-of-Life)（對於商業授權持有者，將於 2023-12-08 達到 EOL）。
已從 ImageQt 移除對 PyQt5 和 PySide2 的支援。請升級至 PyQt6 或 PySide6 作為替代。
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 的 command 參數¶
自 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 版本移除。
IOError 在 Python 3.3 中已合併至 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-01-01 達到生命週期結束 (End-of-Life)。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 達到生命週期結束 (End-of-Life)。其 Python 繫結也已 EOL：PyQt4 自 2018-08-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 版本移除。
為了採用上游的 olefile Python 套件，PIL.OleFileIO 已在 Pillow 4.0.0 (2017-01) 中作為供應商檔案移除，並在 5.0.0 (2018-01) 中以 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。