Why Embedding Images Directly Into a Found Image's Action Is a Bad Idea

Howdy folks, I'm writing this to explain why it is better to use file paths to reference images in any found image action instead of embedding the image directly in the action's image well (usually done by clicking and dragging the image into the square box).

Your entire macro library is stored in a single plist file in Keyboard Maestro's Application Support directory. It is usually only a couple of MB in size (unless you're like me and have over 1,000 macros). Any change you make to any macro updates the entire plist file. This is not a big deal when you have very few macros, but when you start building your macro library this file grows as well. One of the biggest things that affects the size of this file is embedding images directly into a macro, because essentially Keyboard Maestro makes a copy of the image in the plist file itself, causing it to grow substantially.

To give you an idea of how much having an image directly embedded in a macro, one of my largest macros had 21,268 lines of code (retrieved via copying macro as XML and pasting into BBEdit, and reading the line number in the status bar). I had only two images embedded into the macro. I replaced these two images with a file reference, and the macro then had only 3,014 lines of code.

While this is quite impressive in and of itself, imagine having a lot of macros using found image actions, where the image(s) is/are embedded in the action(s) itself. Your plist file will grow to very large sizes. Now, why does this matter? Because as mentioned, every time you edit a macro, and by edit, this could mean typing one single letter into one single action, title, or even enabling/disabling a macro, this modifies that master file. This will cause the Keyboard Maestro Editor (not the Engine which executes the macros) to run significantly slower since it has to continuously modify a larger file.

To give you an idea of how much images bloat a macro's size, take a look at the following four examples.

Macro 1: Compare Found Image Macro Size (7 KB image embedded in action's image well)
It has a 7 KB image embedded directly in the action's image well. The macro has 266 lines of code.

Image: Macro 1 (click to expand/collapse)

Macro 2: Compare Found Image Macro Size (217 KB image embedded in action's image well)
It has a 217 KB image embedded directly in the action's image well. The macro has 14,791 lines of code.

Image: Macro 2 (click to expand/collapse)

Macro 3: Compare Found Image Macro Size (2 MB image embedded in action's image well)
It has a 2 MB image embedded directly in the action's image well. The macro has 64,382 lines of code!

Image: Macro 3 (click to expand/collapse)

Macro 4: Compare Found Image Macro Size (image referenced in action's image well)
This has an image referenced by it's file path, and has no image embedded directly in the action's image well. The macro has only 63 lines of code!

Image: Macro 4 (click to expand/collapse)

Removing just macro 3 (the one with the 2 MB image in it) reduces the Keyboard Maestro plist from 9.4 MB to 6.9 MB. Obviously, it is unlikely you would build a macro with such a large image embedded into an action, but you never know. Therefore, it is recommended to use a filepath to reference any images needed in found image actions as this will greatly reduce the Keyboard Maestro macros plist file and ensure the Editor continues to run smoothly.

Hopefully this helps some folks, especially new users, to understand the benefits of using filepaths to reference images instead of placing them directly in the actions themselves.



Totally agree. I made a post, around this time last year, helping someone with this issue (see below):

I think when we are new to Keyboard Maestro, we are enamored with dropping images in that image well. It’s great for quick testing, for a temporary macro or if you don’t have many macros but if it’s permanent, the file path is the way to go. Being that I still have a 2014 iMac, at this time, performance is all I care about. This technique keeps my plist small and manageable.

Good post @cdthomer.



Ah man I knew there was a post or two floating around here somewhere that talked about this issue (and I even mentioned some of these points in one of those posts haha), but I couldn’t find them when I started to write this. Thanks so much for linking to yours!

I think you did a good service by separating the topic. The image well feature is outstanding but it doesn’t come without over usage consequences. If it didn’t have adverse effects, of plist bloat and my machine’s personal performance, I wouldn’t blink an eye in using it. However, I have way too many macros, that use the found image action, to keep storing in that well. I am so glad that Peter made the found image action flexible so we could store images elsewhere. I know there was talk about a database but that may be overkill since there is a solution.

Thanks for posting this!


Is it possible to take images from the image well and place them into a filesystem folder? Or do I need to recreate each screenshot in order to transition existing macros from using the image well to using a file reference?

There's no native way of doing it, but what I did with some macros was simply opening the image's preview in the action (click the image well, then hit the space bar), and then grabbing another screenshot of that image. That may or may not work depending on a variety of factors but it's worth trying.

I wonder if someone has already written a script that check through KM macro plist, and generate the information about macro group, macro, macro action , image data, image size. This can be then be shown in custom prompt window to let users decide which image to use the "image file" approach. Following 80/20 rule of Pareto principle that 20% of the images account for plist' significant file size, this hybrid approach might be feasible to those who have using lot of embedded images , but didn't want to spend too much effort converting to using "file" approach , or just miss the convenience of using embedded image.

I too have this plist growing to 20mb and I using a lot of embedding image out of convenience, and I too curious what images have caused the bloat.

I wonder if this could be useful enough as next project of Dan Thomas who has always created very useful solutions :} ?

1 Like

Thanks maybe this is why my keyboard mastero lags now.
I don’t have the original images anymore…is there a way to fix this ?
Also is it too late now to fix it or can I just replace the pictures the way you described and problem get fixed.
I wish keyboard maestro did this automatically by creat a folder called “found images” in documents or somewhere else in our Mac and link it the way you described…

Hi @cdthomer. Thanks for sharing this information.

Although Find Image on Screen seems like a really cool action, I've had inconsistent behavior with it, thus I only use it as a last resort. (I'm sure a separate thread on Find Image on Screen best practices would help those like me that have struggled with this action. :wink:)

Nonetheless your post reminded me to search my KM library for the largest macros and do some clean-up.

For those like me that have been inspired by @cdthomer to clean house, remember that a Smart Group can be created with a size Search String.

1 Like

I agree wholeheartedly; a useful feature but not always the best one. I too use if as a last resort.

That's a great tip, I have a smart group for macros sorted by size (accomplished via this macro), but I hadn't used that search string until you mentioned it and it's very useful. Thanks for sharing!

When I learned that this option was better, I created a Keyboard Maestro Found Images folder inside of the Library/Application Support/Keyboard Maestro folder. I placed it here because this folder is backed up every afternoon.

In addition to removing the images from the Found Image well area, I changed every Macro and Group Icon to be a Keyboard Maestro Icon Chooser Character. You would be amazed of how much space I saved with that as well. I call this my rookie phase because I thought I was being cute while customizing everything. Now, Speed and Performance take precedence over everything.


Haha I did that some time back and it does make a big difference. I just went through and did it again and shrunk my file from 6.5 MB to 4.8 MB :laughing:

Thanks so much @cdthomer providing these examples.

I am probably one of the noobs that uses the most amount of images embedded in macros in the world. :joy:

Since these macros have been created over years now of course I also don't have the originals. But it is easily possible to copy them and paste them into an image editor. I am using i.e. SnagIt from Techsmith a lot and I can copy/paste back and forth between KM and SnagIt.

The only problem I have is that it will probably take decades to clean up my whole library. :flushed:

But that's my issue and I'll start with the biggest ones. Thanks again and thanks also to @_jims for the tip with using a smart group. :+1:


It seems that macros that have graphics in Comment actions or Display Text (option: Display text in window) action can also cause that same plist bloat.

Yea that makes sense as really any image that is placed anywhere in a macro will be copied to the master plist file.

1 Like

BTW, @cdthomer, how did you determine the line counts for each of the macros?

Hopefully it’s automated. :grinning:

1 Like

I simply copied the macros' XML and pasted in BBEdit and then looked how many lines it said it had in the status bar :laughing:

1 Like

Oh, that makes sense. For some reason I was thinking you might be combing through the plist.

Haha no, I'd be terrified of accidentally screwing something up (I could make a copy of course) so I just went straight to the macros' XML.

1 Like

So here's something I just discovered. Having an image set as a macro's icon increases the size of the macro (and KM plist file), but having an image set as a macro group's icon appears not to affect it.

For instance here is a screenshot of my macro group's info showing 271,935 as it's size with a custom icon.

Here's the same macro group without the custom icon but showing the same size. The screenshot was taken just a few seconds after the first, with no changes made to the macros within.