IMAGE

What it does

IMAGE(source, [alt_text], [sizing], [height], [width])

IMAGE is the function that broke the assumption that a formula returns a scalar. It does not return a picture file, a URL, or text: it returns a rich value that the host renders in the cell, and that can be sorted, filtered, referenced and copied like any other cell value.

The retrieval itself is not the function's semantics. Microsoft's constraints make that clear and are worth reading as a policy specification rather than as trivia:

• HTTPS only. The source must use https.
• Supported formats: BMP, JPG/JPEG, GIF, TIFF, PNG, ICO and WEBP, with WEBP unsupported on Web and Android.
• No authentication. Images requiring authentication will not render.
• No redirects. Redirected URLs are blocked, explicitly for security reasons.

That last pair is the design statement: IMAGE will only fetch something a plain anonymous GET to a fixed HTTPS URL returns. It is deliberately not a general web fetcher, and the contrast with WEBSERVICE — which allows redirects and returns arbitrary text — is instructive about how Microsoft's posture on formula-initiated network access changed between the two functions.

Arguments

IMAGE(source, [alt_text], [sizing], [height], [width]) — arity 1 to 5, matching the reference engine's recorded arity.

• source (required) — the HTTPS URL of the image file. Microsoft notes a 255-character limit on the URL as written in the formula, with the documented workaround of referencing a cell that contains the longer URL. This is the same inline-versus-referenced asymmetry the cube functions carry, and it catches generated workbooks the same way.

• alt_text (optional) — alternative text describing the image for accessibility. It is a real payload field, not a comment: it is what a screen reader announces.

• sizing (optional) — one of four modes:

  Value	Behaviour
  0	fit the image in the cell, preserving aspect ratio
  1	fill the cell, ignoring aspect ratio
  2	keep the original image size, which may exceed the cell
  3	use the custom height and width arguments

• height (optional) — custom height in pixels; used only when sizing is 3.

• width (optional) — custom width in pixels; used only when sizing is 3. If only one of the two is supplied, the aspect ratio is preserved.

The argument interaction that trips people up is sizing versus height/width, and it is stricter than it looks. Supplying height or width with sizing 0, 1 or 2 is documented as a #VALUE! error — not an ignored argument. Excel does not usually behave this way; unused optional arguments are more often tolerated. Here the combination is validated, in both directions: sizing 3 without valid height and width is likewise #VALUE!.

Try it

This example needs an Excel service or external provider that OneCalc cannot supply in this preview.

Quirks

Result and edge cases

A rich value that the host renders in place. The edges worth naming:

• It is a cell value, not a floating object. Unlike a pasted picture, an IMAGE result moves, sorts and filters with its row. That is the entire reason the function exists.
• The image is fetched, not embedded. The workbook holds a reference. A workbook that displays correctly on the author's machine may show nothing on a machine without network access to the host, and archival copies are not self-contained.
• alt_text is part of the value. Changing it changes the value, not merely a display attribute.

Errors

As documented by Microsoft, #VALUE! covers a notably wide set of distinct causes:

• the image format is unsupported;
• source or alt_text is not a string;
• sizing is not between 0 and 3;
• sizing is 3 but height and width are missing or invalid;
• sizing is 0, 1 or 2 but width or height was supplied anyway.

Two further codes are documented, and they are the two extended-family codes that the value-universe chapter lists for precisely this situation:

• #CONNECT! — an internet-connection or server problem.
• #BLOCKED! — security settings are blocking access.

IMAGE is therefore one of the clearest published cases of the extended error family being reachable from an ordinary worksheet formula, and a useful anchor for anyone trying to understand what #CONNECT! and #BLOCKED! are for.

How to implement

Notes for implementers

• Argument validation is unusually strict and cross-argument. sizing and height/width are validated against each other in both directions, which means validation cannot be done per-argument.
• The 255-character inline URL limit is an Excel behaviour, not a URL standard, and must be enforced as such.
• The security posture — HTTPS only, no redirect following, no authenticated fetches — is part of the function's contract, not an environmental accident. An implementation that follows redirects is more permissive than the documented function.
• NonVolatile plus ExternalEventDependent is an interesting pair: the function is not re-evaluated on every calculation, yet its rendered result depends on a remote resource that can change or vanish. Cache and refresh policy is host behaviour and is not specified by the function.

Rust code

This entry has no Rust implementation yet.

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• WEBSERVICE — the older formula-initiated fetch. Both reach the network from a cell; IMAGE is narrower by design (HTTPS only, no redirects, no authentication) and returns a rich value rather than text.
• HYPERLINK — returns text plus a presentation hint, and is the classic example of a function whose result is core-valued but display-affected. IMAGE goes a step further: its result is genuinely rich.
• Linked data types (Stocks, Geography) and STOCKHISTORY — the other modern provider-backed surfaces. Linked data types share IMAGE's rich-value machinery; STOCKHISTORY shares its provider dependence but returns an ordinary spilled array.
• Pasted pictures and "Place in Cell" images — the user-interface features that produce the same kind of in-cell image without a formula. Readers confuse the two constantly; the difference is that only the formula form recalculates.

Named variants

No named variants are recorded yet.