Miskatonic University Press

Image display size in Org


I just discovered that it’s possible to change the size of an image as displayed in Org while leaving the actual file unchanged. This is great: I can scale it down so it’s just large enough I know what it is but it doesn’t get in my way or take up much real estate.

The variable is org-image-actual-width. C-h v org-image-actual-width shows the documentation:

org-image-actual-width is a variable defined in ‘org.el’. Its value is t

Documentation: Should we use the actual width of images when inlining them?

When set to t, always use the image width.

When set to a number, use imagemagick (when available) to set the image’s width to this value.

When set to a number in a list, try to get the width from any #+ATTR.* keyword if it matches a width specification like

#+ATTR_HTML: :width 300px

and fall back on that number if none is found.

When set to nil, try to get the width from an #+ATTR.* keyword and fall back on the original width if none is found.

This requires Emacs >= 24.1, build with imagemagick support.

(I build Emacs from source, and it has ImageMagick support, though I forget if I had to do anything to get that working. I think just installing ImageMagick is enough. Do ./configure | grep -i imagemagick to check if Emacs knows about it.)

I could set the variable in an init file:

(setq org-image-actual-width nil)

But for now I’m just using it as a file local variable, with this as the first line of the Org file:

# -*- org-image-actual-width: nil; -*-

Then I have, for example, this raw text:

#+NAME: fig:moodleviz
#+CAPTION: Screenshot from Moodleviz.
#+ATTR_ORG: :width 600
#+ATTR_LATEX: :width 5in

That image is 1520 pixels wide (wider than my personal laptop—it’s a screenshot taken on a larger screen) and it’s annoying to move by it up or down, so shrinking the displayed size is great. It looks like this scaled down to 600 pixels wide:

Image resized to be smaller.
Image resized to be smaller.

ATTR_LATEX shrinks the image to a nice size when I export the document to PDF. There is no HTML version so I don’t care about resizing for that.