---
title: "Insert an image in a Word document in C#"
url: https://recursiveai.org/onedocument/cookbook/insert-image-in-word-document/
description: "Insert a PNG, JPEG, GIF or BMP in a Word document in C# with OneDocument. Set the size and alt text, and save the image inline in a DOCX."
version: "1.0.0"
---

# Insert an image in a Word document in C#

**OneDocument** is a free, open-source Word, Excel and PowerPoint document library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneDocument.Documents) · [GitHub](https://github.com/recursive-ai-oss/onedocument-csharp) · [Docs](https://recursiveai.org/onedocument/docs/) · [Download example (.zip)](https://recursiveai.org/onedocument/cookbook/insert-image-in-word-document/insert-image-in-word-document.zip)

Add the picture inline, in the text flow.

```shell
dotnet add package RecursiveAI.OneDocument.Documents
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OneDocument.Documents;
using var doc = Document.Create();
var png = File.ReadAllBytes("swatches.png");
doc.Body.AddPicture(png, widthPoints: 72,
    altText: "Blue and yellow swatches");
doc.SaveAs("swatches.docx");
Console.WriteLine("Wrote swatches.docx");
```

Unzip [the example](https://recursiveai.org/onedocument/cookbook/insert-image-in-word-document/insert-image-in-word-document.zip), then `dotnet run`.

This writes `swatches.docx` with the picture in its own paragraph. Use `swatches.png` from the download (24 × 12 pixels, blue on the left and yellow on the right), or replace its path with the path to any PNG or JPEG.

```text
Wrote swatches.docx
```

## The full program

The program puts the same picture after “Palette:” in the same paragraph. It opens the saved DOCX as a zip to read back the embedded file, alt text, and displayed size.

```csharp
using System.IO.Compression;
using System.Xml.Linq;
using RecursiveAI.OneDocument.Documents;

const string output = "swatches.docx";
using (var doc = Document.Create())
{
    var paragraph = doc.Paragraphs.Single();
    paragraph.AddRun("Palette: ");
    paragraph.AddPicture(File.ReadAllBytes("swatches.png"),
        widthPoints: 72, altText: "Blue and yellow swatches");
    doc.SaveAs(output);
}

using var package = ZipFile.OpenRead(output);
var image = package.Entries.Single(e => e.FullName.StartsWith("word/media/"));
using var main = package.GetEntry("word/document.xml")!.Open();
var xml = XDocument.Load(main);
XNamespace wp = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
var inline = xml.Descendants(wp + "inline").Single();
var size = inline.Element(wp + "extent")!;
Console.WriteLine($"Wrote {output}");
Console.WriteLine($"Embedded PNG: {image.Length} bytes");
Console.WriteLine($"Alt text: {(string?)inline.Element(wp + "docPr")?.Attribute("descr")}");
Console.WriteLine($"Inline size: {(long)size.Attribute("cx")! / 12700} × {(long)size.Attribute("cy")! / 12700} pt");
```

`dotnet run` prints:

```text
Wrote swatches.docx
Embedded PNG: 85 bytes
Alt text: Blue and yellow swatches
Inline size: 72 × 36 pt
```

`AddPicture` accepts PNG, JPEG, GIF, or BMP bytes. It throws `ArgumentException` when it can’t recognize a supported picture header or when the supplied size isn’t positive and finite.

## Variations

### Append a picture to an existing DOCX

Use the `swatches.docx` made by the full program as the input. This adds another copy of the PNG at the end and saves a separate document. Setting just the height keeps the picture’s proportions.

```csharp
using RecursiveAI.OneDocument.Documents;

using var doc = Document.Open("swatches.docx");
var png = File.ReadAllBytes("swatches.png");
doc.Body.AddPicture(png, heightPoints: 24,
    altText: "Blue and yellow swatches");
doc.SaveAs("with-picture.docx");
Console.WriteLine("Wrote with-picture.docx");
```

```text
Wrote with-picture.docx
```

## Related recipes

- [Create a Word document in C#](https://recursiveai.org/onedocument/cookbook/create-word-document/)
- [Add a table to a Word document in C#](https://recursiveai.org/onedocument/cookbook/add-table-to-word/)
- [Read a Word document in C#](https://recursiveai.org/onedocument/cookbook/read-word-document/)

## The short answer

Read the picture bytes, call `AddPicture`, and save the document as DOCX. Call it on the body to add a picture in its own paragraph at the end, or on a paragraph to append the picture after that paragraph’s existing content. In OneDocument 1.0.0, `AddPicture` cannot insert a floating picture or wrap text around it; see [Floating objects and text wrap](https://recursiveai.org/onedocument/docs/layout-floats/) for how OneDocument renders pictures that are already anchored in a document.

## How do I insert a PNG image into Word?

Pass the bytes you read from the PNG directly to `AddPicture`. OneDocument checks the image header, not its filename extension. The [authoring API](https://recursiveai.org/onedocument/docs/authoring/) writes the image bytes into a media part of the DOCX and inserts a reference to it in the paragraph. The document therefore doesn’t need the original PNG file beside it when you open it. `AddPicture` doesn’t decode the pixels, so an accepted header doesn’t guarantee the full image is intact.

When editing an existing Word document, open it with `Document.Open` rather than `Document.Create`. Call `AddPicture` on the paragraph where you want the image to appear after the text. Call it on the body instead if you want the picture at the end, like the variation above. Save to a different filename if you want to keep the original document unchanged.

## How do I resize a picture in Word without stretching it?

Supply either `widthPoints` or `heightPoints`, not both. OneDocument computes the other side from the image’s pixel dimensions. A point is 1/72 inch, so `widthPoints: 72` displays the sample image at one inch wide and half an inch high. The file keeps the original pixels; the size you specify is for the layout. Supplying both dimensions sets both sides independently. If you supply neither, OneDocument uses the pixel dimensions at 96 dpi and scales the picture down to fit a maximum width of six inches.

## How do I add alt text to an image in Word?

Pass `altText` to `AddPicture` when you insert the image. Describe what a reader needs from it rather than repeating the filename. For the sample, “Blue and yellow swatches” conveys the content without seeing the pixels. In the saved DOCX, the description is stored on the inline picture’s drawing properties (`wp:docPr`, `descr`), separate from any visible text in the paragraph.
