<!--
{
  "availability" : [
    "iOS: 13.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSImage",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSImage"
  },
  "title" : "NSImage"
}
-->

# NSImage

A high-level interface for manipulating image data.

```
class NSImage
```

## Overview

You use instances of [`NSImage`](/documentation/AppKit/NSImage) to load existing images, create new images, and draw the resulting image data into your views. Although you use this class predominantly for image-related operations, the class itself knows little about the underlying image data. Instead, it works in conjunction with one or more image representation objects (subclasses of [`NSImageRep`](/documentation/AppKit/NSImageRep)) to manage and render the image data. For the most part, these interactions are transparent.

The  class serves many purposes, providing support for the following tasks:

- Loading images stored on disk or at a specified URL.
- Drawing images into a view or graphics context.
- Providing the contents of a <doc://com.apple.documentation/documentation/QuartzCore/CALayer> object.
- Creating new images based on a series of captured drawing commands.
- Producing versions of the image in a different format.

The `NSImage` class itself is capable of managing image data in a variety of formats. The specific list of formats is dependent on the version of the operating system but includes many standard formats such as TIFF, JPEG, GIF, PNG, and PDF among others. AppKit manages each format using a specific type of image representation object, whose job is to manage the actual image data. You can get a list of supported formats using the methods described in Determining Supported Types of Images.

### Using Images with Core Animation Layers

Although you can assign an `NSImage` object directly to the <doc://com.apple.documentation/documentation/QuartzCore/CALayer/contents> property of a <doc://com.apple.documentation/documentation/QuartzCore/CALayer> object, doing so may not always yield the best results. Instead of using your image object, you can use the [`layerContents(forContentsScale:)`](/documentation/AppKit/NSImage/layerContents(forContentsScale:)) method to obtain an object that you can use for your layer’s contents. The image created by that method serves as the contents of a layer, which also supports all of the layer’s gravity modes. By contrast, the `NSImage` class supports only the <doc://com.apple.documentation/documentation/QuartzCore/CALayerContentsGravity/resize>, <doc://com.apple.documentation/documentation/QuartzCore/CALayerContentsGravity/resizeAspect>, and <doc://com.apple.documentation/documentation/QuartzCore/CALayerContentsGravity/resizeAspectFill> modes.

Before calling the [`layerContents(forContentsScale:)`](/documentation/AppKit/NSImage/layerContents(forContentsScale:)) method, use the [`recommendedLayerContentsScale(_:)`](/documentation/AppKit/NSImage/recommendedLayerContentsScale(_:)) method to get the recommended scale factor for the resulting image. The code listing below shows a typical example that uses the scale factor of a window’s backing store as the desired scale factor. From that scale factor, the code gets the scale factor for the specified image object and creates an object that you assign to the layer. You might use this code for images that fit the layer bounds precisely or for which you rely on the <doc://com.apple.documentation/documentation/QuartzCore/CALayer/contentsGravity> property of the layer to position or scale the image.

Listing 1. Assigning an image to a layer

```objc
static void updateLayerWithImageInWindow1(NSImage *image, CALayer *layer, NSWindow *window) {
   CGFloat desiredScaleFactor = [window backingScaleFactor];
   CGFloat actualScaleFactor = [image recommendedLayerContentsScale:desiredScaleFactor];
 
   id layerContents = [image layerContentsForContentsScale:actualScaleFactor];
 
   [layer setContents:layerContents];
   [layer setContentsScale:actualScaleFactor];
}
```

## Topics

### Creating Images by Name

  <doc://com.apple.documentation/documentation/UIKit/configuring-and-displaying-symbol-images-in-your-ui>

[`init(named:)`](/documentation/AppKit/NSImage/init(named:))

Returns the image object associated with the specified name.

[`init(systemSymbolName:accessibilityDescription:)`](/documentation/AppKit/NSImage/init(systemSymbolName:accessibilityDescription:))

Creates a symbol image with the system symbol name and accessibility description you specify.

[`init(systemSymbolName:variableValue:accessibilityDescription:)`](/documentation/AppKit/NSImage/init(systemSymbolName:variableValue:accessibilityDescription:))

Creates a symbol image with the system symbol name and variable value you specify.

[`init(symbolName:variableValue:)`](/documentation/AppKit/NSImage/init(symbolName:variableValue:))

Creates a symbol image with the symbol name and variable value you specify.

[`init(symbolName:bundle:variableValue:)`](/documentation/AppKit/NSImage/init(symbolName:bundle:variableValue:))

Creates a symbol image with the specified symbol name and variable value.

[`init(resource:)`](/documentation/AppKit/NSImage/init(resource:))

Initialize a `NSImage` with an image resource.

[`setName(_:)`](/documentation/AppKit/NSImage/setName(_:))

Registers the image object under the specified name.

[`name()`](/documentation/AppKit/NSImage/name())

Returns the name associated with the image, if any.

[`NSImage.Name`](/documentation/AppKit/NSImage/Name-swift.typealias)

Named images, defined by the system or you, for use in your app.

[`init(imageLiteralResourceName:)`](/documentation/AppKit/NSImage/init(imageLiteralResourceName:))

Creates an image initialized with the specified resource name.

### Creating Dynamically Drawn Images

[`init(size:flipped:drawingHandler:)`](/documentation/AppKit/NSImage/init(size:flipped:drawingHandler:))

Creates and returns an image object whose contents are drawn using the specified block.

### Creating Images from Resource Files

[`init(byReferencingFile:)`](/documentation/AppKit/NSImage/init(byReferencingFile:))

Initializes and returns an image object using the specified file.

[`init(byReferencing:)`](/documentation/AppKit/NSImage/init(byReferencing:))

Initializes and returns an image object using the specified URL.

[`init(contentsOfFile:)`](/documentation/AppKit/NSImage/init(contentsOfFile:))

Initializes and returns an image object with the contents of the specified file.

[`init(contentsOf:)`](/documentation/AppKit/NSImage/init(contentsOf:))

Initializes and returns an image object with the contents of the specified URL.

### Creating Images from Existing Data

[`init(data:)`](/documentation/AppKit/NSImage/init(data:))

Initializes and returns an image object using the provided image data.

[`init(dataIgnoringOrientation:)`](/documentation/AppKit/NSImage/init(dataIgnoringOrientation:))

Initializes and returns an image object using the provided image data and ignoring the EXIF orientation tags.

[`init(cgImage:size:)`](/documentation/AppKit/NSImage/init(cgImage:size:)-8oznv)

Creates a new image using the contents of the provided image.

[`init(pasteboard:)`](/documentation/AppKit/NSImage/init(pasteboard:))

Initializes and returns an image object with data from the specified pasteboard.

[`init(coder:)`](/documentation/AppKit/NSImage/init(coder:))

Initializes and returns an image object from data in an unarchiver.

### Creating Empty Images

[`init(size:)`](/documentation/AppKit/NSImage/init(size:))

Initializes and returns an image object with the specified dimensions.

### Creating Symbol Images

[`withSymbolConfiguration(_:)`](/documentation/AppKit/NSImage/withSymbolConfiguration(_:))

Creates a new symbol image with the specified configuration.

[`NSImage.SymbolConfiguration`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class)

An object that contains the specific font, style, and weight attributes to apply to a symbol image.

### Getting the Symbol Image Configuration

[`symbolConfiguration`](/documentation/AppKit/NSImage/symbolConfiguration-swift.property)

The configuration details for a symbol image.

### Managing Loading and Drawing of Images

[`delegate`](/documentation/AppKit/NSImage/delegate)

The image’s delegate object.

[`NSImageDelegate`](/documentation/AppKit/NSImageDelegate)

A set of optional methods that you can use to respond to drawing failures and manage incremental loads.

### Setting Attributes of Images

[`size`](/documentation/AppKit/NSImage/size)

The size of the image.

[`isTemplate`](/documentation/AppKit/NSImage/isTemplate)

A Boolean value that determines whether the image represents a template image.

[`isTemplate`](/documentation/AppKit/NSImage/isTemplate)

A Boolean value that determines whether the image represents a template image.

### Determining Supported Types of Images

[`canInit(with:)`](/documentation/AppKit/NSImage/canInit(with:))

Tests whether the image can create an instance of itself using pasteboard data.

[`imageTypes`](/documentation/AppKit/NSImage/imageTypes)

Returns an array of UTI strings identifying the image types supported by the registered image representation objects, either directly or through a user-installed filter service.

[`imageUnfilteredTypes`](/documentation/AppKit/NSImage/imageUnfilteredTypes)

Returns an array of UTI strings identifying the image types supported directly by the registered image representation objects.

### Working with Representations of Images

[`addRepresentation(_:)`](/documentation/AppKit/NSImage/addRepresentation(_:))

Adds the specified image representation object to the image.

[`addRepresentations(_:)`](/documentation/AppKit/NSImage/addRepresentations(_:))

Adds an array of image representation objects to the image.

[`representations`](/documentation/AppKit/NSImage/representations)

An array containing all of the image object’s image representations.

[`removeRepresentation(_:)`](/documentation/AppKit/NSImage/removeRepresentation(_:))

Removes and releases the specified image representation.

[`bestRepresentation(for:context:hints:)`](/documentation/AppKit/NSImage/bestRepresentation(for:context:hints:))

Returns the best representation of the image for the specified rectangle using the provided hints.

[`NSImageRep.HintKey`](/documentation/AppKit/NSImageRep/HintKey)

Constants for the keys to include in a hints dictionary when drawing the image.

[`NSImage.LayoutDirection`](/documentation/AppKit/NSImage/LayoutDirection)

Constants that describe the layout direction for the image.

### Setting the Representation Selection Criteria for Images

[`prefersColorMatch`](/documentation/AppKit/NSImage/prefersColorMatch)

A Boolean value that indicates whether the image prefers to choose image representations using color-matching or resolution-matching.

[`usesEPSOnResolutionMismatch`](/documentation/AppKit/NSImage/usesEPSOnResolutionMismatch)

A Boolean value that indicates whether EPS representations are preferred when no other representations match the resolution of the device.

[`matchesOnMultipleResolution`](/documentation/AppKit/NSImage/matchesOnMultipleResolution)

A Boolean value that indicates whether image representations whose resolution is an integral multiple of the device resolution are a match.

### Drawing Images

[`draw(in:)`](/documentation/AppKit/NSImage/draw(in:))

Draws the image in the specified rectangle.

[`draw(at:from:operation:fraction:)`](/documentation/AppKit/NSImage/draw(at:from:operation:fraction:))

Draws all or part of the image at the specified point in the current coordinate system.

[`draw(in:from:operation:fraction:)`](/documentation/AppKit/NSImage/draw(in:from:operation:fraction:))

Draws all or part of the image in the specified rectangle in the current coordinate system.

[`draw(in:from:operation:fraction:respectFlipped:hints:)`](/documentation/AppKit/NSImage/draw(in:from:operation:fraction:respectFlipped:hints:))

Draws all or part of the image in the specified rectangle respecting the hints and the orientation of the current coordinate system.

[`drawRepresentation(_:in:)`](/documentation/AppKit/NSImage/drawRepresentation(_:in:))

Draws the image using the specified image representation object.

[`NSCompositingOperation`](/documentation/AppKit/NSCompositingOperation)

Constants that describe compositing operators in terms of source and destination images, each having an opaque and transparent region.

### Managing Drawing Options

[`isValid`](/documentation/AppKit/NSImage/isValid)

A Boolean value that indicates whether it is possible to draw an image representation.

[`backgroundColor`](/documentation/AppKit/NSImage/backgroundColor)

The background color for the image.

[`capInsets`](/documentation/AppKit/NSImage/capInsets)

The cap insets for the image.

[`resizingMode`](/documentation/AppKit/NSImage/resizingMode-swift.property)

The resizing mode for the image.

[`NSImage.ResizingMode`](/documentation/AppKit/NSImage/ResizingMode-swift.enum)

Constants that describe the resizing mode for the image.

### Working with Alignment Metadata

[`alignmentRect`](/documentation/AppKit/NSImage/alignmentRect)

A rectangle that you can use to position the image during layout.

### Managing Caching Options

[`cacheMode`](/documentation/AppKit/NSImage/cacheMode-swift.property)

The image’s caching mode.

[`recache()`](/documentation/AppKit/NSImage/recache())

Invalidates and frees offscreen caches of all image representations.

[`NSImage.CacheMode`](/documentation/AppKit/NSImage/CacheMode-swift.enum)

Constants that specify the caching policy on a per-image basis.

### Producing TIFF Data for Images

[`tiffRepresentation`](/documentation/AppKit/NSImage/tiffRepresentation)

A data object containing TIFF data for all of the image representations in the image.

[`tiffRepresentation(using:factor:)`](/documentation/AppKit/NSImage/tiffRepresentation(using:factor:))

Returns a data object that contains TIFF data with the specified compression settings for all of the image representations in the image.

### Producing Core Graphics Images

[`cgImage(forProposedRect:context:hints:)`](/documentation/AppKit/NSImage/cgImage(forProposedRect:context:hints:))

Returns a Core Graphics image based on the contents of the current image object.

### Managing Incremental Loads

[`cancelIncrementalLoad`](/documentation/AppKit/NSImage/cancelIncrementalLoad)

Cancels the current download operation, if any, for an incrementally loaded image.

### Hit-Testing Images

[`hitTest(_:withDestinationRect:context:hints:flipped:)`](/documentation/AppKit/NSImage/hitTest(_:withDestinationRect:context:hints:flipped:))

Returns whether the destination rectangle would intersect a non-transparent portion of the image.

### Managing Image Accessibility

[`accessibilityDescription`](/documentation/AppKit/NSImage/accessibilityDescription)

The image’s accessibility description.

### Using Images with Core Animation

[`layerContents(forContentsScale:)`](/documentation/AppKit/NSImage/layerContents(forContentsScale:))

Returns an object that may be used as the contents of a layer.

[`recommendedLayerContentsScale(_:)`](/documentation/AppKit/NSImage/recommendedLayerContentsScale(_:))

Returns the recommended layer contents scale for this image.

### Managing Axis Matching

[`matchesOnlyOnBestFittingAxis`](/documentation/AppKit/NSImage/matchesOnlyOnBestFittingAxis)

A Boolean value that indicates whether the image matches only on the best fitting axis.

### Localizing Images

[`withLocale(_:)`](/documentation/AppKit/NSImage/withLocale(_:))

Creates and returns a new image with the specified locale.

[`locale`](/documentation/AppKit/NSImage/locale)

The image’s preferred locale for resolving representations, if one has been specified using `-imageWithLocale:`. Otherwise, `nil`.

### Deprecated

[Deprecated Symbols](/documentation/AppKit/nsimage-deprecated-symbols)

Review symbols that are no longer supported, and find the replacements to use instead.

### Enumerations

[`NSImage.DynamicRange`](/documentation/AppKit/NSImage/DynamicRange)

Describes how High Dynamic Range (HDR) image content displays.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)