Image lifecycle¶

• Image.open() Filenames andPath objects are opened as a file.Metadata is read from the open file. The file is left open for further usage.

• Image.Image.load() When the pixel data from the image isrequired,load() is called. The current frame is read intomemory. The image can now be used independently of the underlyingimage file.

  Any Pillow method that creates a new image instance based on another willinternally callload() on the original image and then read the data.The new image instance will not be associated with the original image file.

  If a filename or aPath object was passed toImage.open(), then thefile object was opened by Pillow and is considered to be used exclusively byPillow. So if the image is a single-frame image, the file will be closed inthis method after the frame is read. If the image is a multi-frame image,(e.g. multipage TIFF and animated GIF) the image file is left open so thatImage.Image.seek() can load the appropriate frame.

• Image.Image.close() Closes the file and destroys the core image object.

  The Pillow context manager will also close the file, but will not destroythe core image object. e.g.:

  withImage.open("test.jpg")asimg:img.load()assertimg.fpisNoneimg.save("test.png")

The lifecycle of a single-frame image is relatively simple. The file mustremain open until theload() orclose() function is called or thecontext manager exits.

Multi-frame images are more complicated. Theload() method is nota terminal method, so it should not close the underlying file. In general,Pillow does not know if there are going to be any requests for additionaldata until the caller has explicitly closed the image.

Complications¶

• TiffImagePlugin has some code to pass the underlying file descriptor intolibtiff (if working on an actual file). Since libtiff closes the filedescriptor internally, it is duplicated prior to passing it into libtiff.

• After a file has been closed, operations that require file access will fail:

  withopen("test.jpg","rb")asf:im5=Image.open(f)im5.load()# FAILS, closed filewithImage.open("test.jpg")asim6:passim6.load()# FAILS, closed file

Proposed file handling¶

• Image.Image.load() should close the image file, unless there aremultiple frames.

• Image.Image.seek() should never close the image file.

• Users of the library should use a context manager or callImage.Image.close() on any image opened with a filename orPathobject to ensure that the underlying file is closed.