How to create an icon for your charm

See also:

You’ve released your charm to the stable channel on Charmhub. This document shows you how to make it more stand out by adding a unique and recognisable icon for it.


Icon specifications

Before we start actually making the icon though, we should be aware of the specifications required by the charm store. This is to ensure a consistent experience for the users, and icons failing to meet this spec will be rejected.

A charm icon is an SVG format image where the canvas size is 100x100 pixels. It consists of a circle with a flat color and a logo. It has to be saved as icon.svg in your charm’s root directory.

There is no specification to design the logo: it can be a white (or black) monochromatic symbol, a colored logo, or whatever is best. However, it’s best to leave some padding between the edges of the circle and the logo.

Creating an icon

If meeting the above spec seems more complicated than creating your charm in the first place, then fear not, because we have an easy step-by-step guide for you. Before you start you will need:

  • A vector graphic editor. We strongly recommend the cross-platform and most excellent Inkscape for all your vector graphic needs.
  • The template file. (right-click > Save link as…)
  • An existing logo you can import, or the ability to draw one in Inkscape.

Once you have those, fire up Inkscape and we can begin!

Open the template

From Inkscape load the icon.svg file. Select the Layer called “Background Circle”, either from the drop down at the bottom, or from the layer dialog.

Add colour

Select Object and then Fill and Stroke from the menu to adjust the color.

Draw something

Draw your shape within the circle. If you already have a vector logo, you can import it and scale it within the guides. Inkscape also has plenty of drawing tools for creating complex images.

If you import a bitmap image to use, be sure to convert it into a vector file and delete the bitmap.

Cloud icon: “Cloud by unlimicon from the Noun Project” [CC BY]

To add the icon to the charm’s Charmhub page, save it as icon.svg, place it in the root directory of the charm, and then publish the charm to latest/stable.

Validate your icon

You can validate your icon at The page checks the most basic issues that prevent icons working.

And finally… some quick Dos and Don’ts

Icons should not be overly complicated. Charm icons are displayed in various sizes (from 160x160 to 32x32 pixels) and they should be always legible. In Inkscape, the ‘Icon preview’ tool can help you to check the sharpness of your icons at small sizes.

Symbols should have a similar weight on all icons: avoid too thin strokes and use the whole space available to draw the symbol within the limits defined by the padding. However, if the symbol is much wider than it is high, it may overflow onto the horizontal padding area to ensure its weight is consistent.

Do not use glossy materials unless they are parts of a logo that you are not allowed to modify.

BEWARE: unless your charm has (or has had at some point) a release in the stable channel, the icon will not be visible. That is because charmhub only updates the metadata for a charm on stable channel releases (by design). So either release to stable and then roll it back, or wait until your charm is ready for a “stable” stable release.

1 Like

hi there,
I try to realize an icon as you’ve suggested us but after to run the build of my local charm and deploy that on Juju Gui I don’t see that, is there another thing to make? thanks

Have you saved the icon as icon.svg in the root of the charm directory?

Hi @timClicks

yes it has icon.svg format… on another post I’ve received this answer

There is an authentication limitation in how the GUI interacts with Juju around displaying icons for local charms which is probably what you’re seeing there. We won’t be addressing this in the GUI but it’s on our roadmap to resolve in the upcoming replacement for the GUI, the Juju Dashboard.

Being that a my proof to create a charm, maybe the issue is that.

That looks like a scaling issue. Are you embedding a bitmap (png/json) into the SVG file?

Awesome tutorial. Thank you so much

1 Like

Added a clarification that the icon won’t show unless you’ve had a stable release with the icon.

Thanks a lot for this tutorial!

The one thing I was missing is how to actually configure the charm to use it or where to put it so that charmcraft automatically uses it.

This was especially confusing, as the existing charms we have do not have an icon.svg in their root, but nonetheless show one on

I did not find anything in the documentation, but at some point my colleagues mentioned that we have an icon.svg in a base charm which is used in all the other charms - so we have some kind of default icon.

Would it be possible to include some information about how this all works?

Thank you!

It looks like this is documented here Build Tactics — Charm Tools documentation