{"id":2386,"date":"2026-10-23T15:55:01","date_gmt":"2026-10-23T07:55:01","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2386"},"modified":"2026-03-29T10:10:02","modified_gmt":"2026-03-29T10:10:02","slug":"how-to-use-rangecopypicture-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangecopypicture-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.CopyPicture in the xlwings API way"},"content":{"rendered":"\n

The Range.CopyPicture<\/code> member in Excel’s object model allows you to copy a range of cells as a picture, which can then be pasted into other locations within Excel or into external applications. This is particularly useful for creating visual snapshots of data, charts, or formatted tables that need to be shared or used in reports, presentations, or dashboards. In xlwings, this functionality is accessible through the API, enabling automation of picture-copying tasks directly from Python scripts.<\/p>\n\n\n\n

The syntax for CopyPicture<\/code> in xlwings follows the Excel object model closely. It is a method that can be called on a Range<\/code> object. The method takes two parameters: Appearance<\/code> and Format<\/code>. These parameters determine how the picture is copied, affecting its visual quality and file format. In xlwings, you invoke it as range_object.api.CopyPicture(Appearance, Format)<\/code>, where range_object<\/code> is an instance of xlwings’ Range<\/code> class. The parameters are optional in Excel, but when specified in xlwings, they should be passed as constants or integer values.<\/p>\n\n\n\n

The Appearance<\/code> parameter controls whether the picture is copied as it appears on screen or as it would look when printed. It accepts two primary values: xlScreen<\/code> (value 1) for screen appearance, which is the default, and xlPrinter<\/code> (value 2) for printer appearance, which may include higher resolution or print-specific settings. The Format<\/code> parameter defines the picture format, with key options being xlPicture<\/code> (value -4147) for bitmap format and xlBitmap<\/code> (value 2) for a bitmap image. In practice, xlPicture<\/code> is commonly used for copying ranges as pictures in Excel. If parameters are omitted, Excel uses default values, typically xlScreen<\/code> and xlPicture<\/code>.<\/p>\n\n\n\n

Here is a table summarizing the parameter options:<\/p>\n\n\n\n

Parameter<\/th>Value (Constant)<\/th>Integer Value<\/th>Description<\/th><\/tr><\/thead>
Appearance<\/td>xlScreen<\/td>1<\/td>Copies the range as it appears on screen.<\/td><\/tr>
<\/td>xlPrinter<\/td>2<\/td>Copies the range as it would look when printed.<\/td><\/tr>
Format<\/td>xlPicture<\/td>-4147<\/td>Copies in picture format (default).<\/td><\/tr>
<\/td>xlBitmap<\/td>2<\/td>Copies as a bitmap image.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

To use CopyPicture<\/code> in xlwings, you first need to establish a connection to an Excel application and workbook. After copying the range as a picture, you can paste it elsewhere using the Paste<\/code> method on a destination range or sheet. Below is a code example that demonstrates this process:<\/p>\n\n\n\n

import xlwings as xw\n\n# Connect to the active Excel instance or create a new one\napp = xw.apps.active\nwb = app.books.active\nsheet = wb.sheets['Sheet1']\n\n# Define the source range to copy as a picture (e.g., cells A1 to D10)\nsource_range = sheet.range('A1:D10')\n\n# Copy the range as a picture with screen appearance and picture format\nsource_range.api.CopyPicture(Appearance=1, Format=-4147) # Using integer values for clarity\n\n# Specify a destination range to paste the picture (e.g., starting at cell F1)\ndest_range = sheet.range('F1')\nsheet.api.Paste(Destination=dest_range.api) # Paste the picture at the destination\n\n# Alternatively, you can use constants from the xlwings.constants module for better readability\nimport xlwings.constants as win32c\nsource_range.api.CopyPicture(Appearance=win32c.xlScreen, Format=win32c.xlPicture)\nsheet.api.Paste(Destination=dest_range.api)\n\n# Save the workbook if needed\nwb.save()<\/code><\/pre>\n\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
The `Range.CopyPicture` member in Excel's object model allows you to copy a range of cells as a pict…<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2386","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2386","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2386"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2386\/revisions"}],"predecessor-version":[{"id":3632,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2386\/revisions\/3632"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2386"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2386"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2386"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}