What this tool does
A favicon is a small binary file with a large number of places to get it wrong, most of which produce an icon that looks fine on the developer's screen and blank or blurry everywhere else. This tool assembles a real multi-size .ico from your PNG, generates the apple-touch-icon and the manifest icons beside it, and then decodes the bytes it just wrote so you can see exactly what is in the container. If an icon is wrong, the reason is in the table.
How it works
The ICO is fully specified and small. ICONDIR is six bytes: a reserved word of zero, a type of 1 for an icon, and a count of the images that follow. Then come 16-byte directory entries, one per image, each carrying a width byte, a height byte, a palette hint, the plane count, the bit depth, the payload length and the offset of the payload measured from the start of the file. The payloads themselves are PNGs, which every current browser accepts inside an .ico.
The detail that breaks hand-rolled generators is the width byte. It is a single byte, and 256 does not fit in one, so the format spends the value 0 on it. Write 256 literally and you have declared a 0 × 0 image, which is why a 256px icon generated by hand comes out as nothing at all. The byte report names this explicitly when it sees a zero width or height, so the file explains its own most common failure.
apple-touch-icon has to be opaque, and the reason is specific rather than fussy: iOS composites a transparent icon onto black instead of onto your page, so a logo with a transparent background ships as a black square with a logo-shaped hole in it. The 180px icon is therefore flattened onto a background colour you choose, and the tool says so rather than quietly producing something that will look broken on an iPhone home screen.
The maskable icon is a cropping problem, not a sizing one. Android adaptive icons are cut by whatever mask the launcher applies — a circle, a squircle, a rounded square — so meaningful content has to sit inside a circle of about 80% of the canvas. On a 512px icon that is a 410px circle, and because a circle inscribed in a square keeps only about 50% of the area, the safe zone is a circle and not the square. One last thing worth knowing: browsers request /favicon.ico at the root of a site with no link tag anywhere in the HTML, which is why it is still the universal fallback.
Worked example
A site needs a favicon.ico, an iOS home-screen icon and a PWA manifest, all from one 1024px PNG.
- The ICO is written with four images: 16, 32, 48 and 256 pixels
- ICONDIR is 6 bytes — 00 00 reserved, 01 00 type, 04 00 count — and the four entries take 64 more, so the first payload starts at byte 70
- The 256px entry stores 00 in both the width and height bytes, which the report flags as meaning 256 rather than 0
- apple-touch-icon.png is produced at 180 × 180, flattened onto white so iOS has nothing to composite
- icon-512-maskable.png is produced with the safe circle marked at 410px
One ZIP holding favicon.ico, apple-touch-icon.png, icon-192.png, icon-512.png, the maskable variant and a valid application/manifest+json. The ICO decodes back to exactly the sizes that were requested, with the 256 entry intact.
Accuracy and limitations
- Browsers cache favicons aggressively. A hard reload, and on some browsers a clear site-data, is often needed before a new icon appears at all.
- The ICO stores PNG payloads only. The older BMP/DIB branch of the format, with its second AND mask and row-padded stride, is not produced.
- apple-touch-icon is flattened on purpose. A transparent iOS icon is composited onto black and ships as a black square.
Frequently asked questions
- Why is my 256px favicon blank or zero-sized?
- Almost always the width byte. The ICO stores each dimension in a single byte, and 256 does not fit, so the format spends the value 0 on it. A generator that writes 256 literally has declared a 0 × 0 image, and the browser draws nothing.
- Why does my favicon look blurry?
- Almost always because there is only one size in the file and it is the wrong one. Browsers ask for 16 on a standard display and 32 on a HiDPI one, and Windows still requests 48, so an .ico should carry all three plus a 256 for the places that look at it closely.
- What sizes does favicon.ico need?
- 16, 32 and 48 pixels cover browser tabs, HiDPI tabs and Windows desktops and title bars. Adding 256 costs one more directory entry and covers the places that display an icon large. Outside the .ico, iOS wants a 180 apple-touch-icon and an installable web app wants 192 and 512.
- Why does my Apple touch icon show as a black square?
- Because it has transparency. iOS composites a transparent icon onto black rather than onto your page, so a logo with a transparent background arrives as a black square with the logo punched out of it. The icon has to be opaque, which is why this tool flattens the 180px export onto a background colour.
- What is a maskable icon and why does it need a safe zone?
- Android adaptive icons are cropped by whatever mask the launcher applies, so artwork near the edge is thrown away. Anything that has to stay visible belongs inside a circle of about 80% of the canvas — on a 512px icon, a 410px circle, which keeps roughly half the area.
- Do I still need favicon.ico if I use a link tag?
- Yes, because browsers request /favicon.ico from the root of a site with no link tag present at all. That fallback request is why the .ico is still the one file worth having, and why a wrong or empty one is what most people see in the tab.