The Short Answer
Quick answer: A VS Code extension's icon must be a PNG of at least 128 x 128 pixels, and Microsoft suggests 256 x 256 for Retina screens. SVG icons are blocked. The Marketplace page header takes one banner color and a dark or light theme. There's no screenshot field. Your README.md becomes the page body, and every image in it must load over https and can't be an SVG, except badges from approved services.
The rest of this guide covers each rule, and what the 30 most installed extensions actually ship.
What I Checked
On 16 November 2026, I read two pages of Microsoft's VS Code docs: the extension manifest reference and the guide to publishing extensions. Together they hold every image and listing rule the Marketplace sets.
Then I pulled the 30 most installed VS Code extensions from the Marketplace's public query service. For each one, I downloaded the icon file it ships, measured it, and noted whether it sets a banner color.
The sample runs from Python, with about 245 million installs, down to CMake, with about 47 million. All 30 are free extensions you've likely seen in the Extensions view.
Every Image and Field at a Glance
Here's the full set of listing items and their rules.
| Item | Rule | Field |
|---|---|---|
| Icon | PNG, at least 128 x 128, 256 x 256 for Retina | icon |
| Banner color | Any hex color | galleryBanner.color |
| Banner theme | dark or light | galleryBanner.theme |
| README images | https only, no SVG | README.md |
| Badges | Approved services only | badges |
| Keywords | 30 at most | keywords |
| Pricing label | Free or Trial | pricing |
All of these sit in your extension's package.json file, except the README itself. The Marketplace takes them from the package you publish, so there's no separate listing form to fill in.
The Icon: 128 x 128 or Bigger
The manifest reference asks for an icon of at least 128 x 128 pixels, and 256 x 256 for Retina screens. The publishing guide adds that it must be a PNG file inside your extension, set by a relative path in the icon field.
The icon shows at the top of your Marketplace page. It also shows in the Extensions view inside VS Code, where list rows are small.
A 256 x 256 PNG is the safe choice. It meets both numbers, and it stays sharp on screens that double the pixels. Keep the shape simple enough to read in a narrow list, since that's where most people see it.
Why SVG Icons Are Blocked
Microsoft's publishing guide is direct about this. For security reasons, vsce, the tool that packages and publishes extensions, won't publish an extension that contains user provided SVG images.
It checks three things. The icon can't be an SVG. Badges listed in package.json can't be SVGs unless they come from a trusted badge service. And images in README.md and CHANGELOG.md can't be SVGs either, with the same badge exception.
If you design your icon as a vector, that's fine. Export it to PNG before you publish, and keep the SVG as your source file.
The Banner Color and Theme
The top of your Marketplace page is a banner. You set its background with galleryBanner.color, as a hex value such as #C80000, and its theme with galleryBanner.theme, which is dark or light.
Microsoft's docs say the theme sets the font used in the banner. They also suggest pairing your icon with a contrasting banner color.
In practice, match the theme to the color. Every extension in my sample that chose dark paired it with a dark color, and every light one used white or yellow. A light color with a dark theme can leave your text hard to read.
Your README Is the Listing Page
The VS Code Marketplace has no screenshot gallery like Google Play or the App Store. Microsoft's docs say the README.md file in your extension's root folder becomes the body of your Marketplace page.
So screenshots, demos and feature tables all go in the README. You can use relative image paths. If package.json has a repository field that points to a public GitHub repository, vsce rewrites relative links to point there, using the main branch by default.
If your images live somewhere else, vsce accepts base URLs for links and images when you package or publish.
README Image Rules
Two rules decide whether your README images pass.
- 1Every image URL must resolve to https. The publishing check rejects plain http image links.
- 2No SVG images, unless they're badges from an approved service.
The same rules cover CHANGELOG.md.
Since the README is your only gallery, treat its first image like a store's first screenshot. Put your best feature on top, show it working in a real editor, and add a short line that says what it does. A long block of text above the first image pushes it out of view.
Badges Come From an Approved List
Badges are the small status images many extensions show, like build status or download counts. Listed in package.json, they appear in the sidebar of your Marketplace page.
Microsoft only allows badges from trusted services. The manifest reference lists 33 address prefixes, including img.shields.io, badgen.net, codecov.io, coveralls.io, snyk.io and vsmarketplacebadges.dev. GitHub badges count only when they come from Workflows.
Need a service that isn't on the list? Microsoft asks you to open an issue on GitHub so it can take a look.
Name, Description and Keywords
Text matters as much as images here, because VS Code's own search uses it. Microsoft's tips say the display name and description appear on the Marketplace and inside VS Code, and both feed text search.
Three rules apply:
- 1The display name must be unique across the Marketplace.
- 2The description is one short line about what the extension does.
- 3Keywords stop at 30. Publishing fails with an error if package.json lists more.
Keywords show up with your other tags on the Marketplace. Pick the words people type, like the language or tool name, not slogans.
Categories: 17 Choices
Each extension picks one or more categories from a fixed list. The manifest reference lists 17, grouped here by kind.
| Group | Categories |
|---|---|
| Code | Programming Languages, Snippets, Linters, Formatters, Debuggers, Testing |
| Look and keys | Themes, Keymaps |
| Tools | SCM Providers, Notebooks, Visualization |
| Data | Data Science, Machine Learning |
| Packs | Extension Packs, Language Packs |
| General | Education, Other |
Pick the narrowest one that fits. A formatter filed under Other is likely harder to find than one filed under Formatters.
Pricing Label, Sponsor Link and Verified Badge
Three extras can sit on your Marketplace page.
- 1A pricing label. Set pricing to Free or Trial, written exactly that way. If you leave it out, the value defaults to Free. It needs vsce 2.10.0 or later.
- 2A sponsor link. Add a sponsor URL so users can support your work. It needs vsce 2.9.1 or later.
- 3A verified badge. You verify a domain tied to your brand. You need an extension on the Marketplace for at least 6 months, and the domain must be registered for at least 6 months.
None of these replace a good icon, but the verified badge adds trust next to your name.
What 30 Top Extensions Use for Icons
Every icon in my sample was a PNG, and every one met the 128 x 128 minimum.
| Icon size | Extensions |
|---|---|
| 128 x 128 | 11 |
| 256 x 256 | 7 |
| 257 x 257 | 2 |
| 600 x 600 | 1 |
| 600 x 607 | 4 |
| 1066 x 1067 | 4 |
| 1316 x 1126 | 1 |
So 19 of 30 reach at least 256 on both sides, the Retina size Microsoft suggests. The other 11 use exactly the minimum, including C/C++, Prettier and GitLens.
Most of the large files come from two Microsoft families, Python and Jupyter, which share one icon file across several extensions each.
Banner Colors in the Sample
Only 12 of the 30 set a banner color. The other 18 left it out.
| Extension | Color | Theme |
|---|---|---|
| Python | #1e415e | dark |
| Live Server | #41205f | dark |
| CMake Tools | #13578c | dark |
| GitLens | #8647ae | dark |
| Docker | #1e1e1e | dark |
| CMake | #5c2d91 | dark |
| Prettier | #ffe04b | light |
The other five were Jupyter extensions, all on white, #ffffff, with a light theme.
So leaving it out is common, even among big names. But it's one line in package.json, and it gives your page a look that matches your icon.
Square or Not
Microsoft's docs give a minimum size, but they don't say the icon must be square. In my sample, 21 of 30 icons were exactly square.
Eight were off by a few pixels: the four Python family icons at 600 x 607, and four Jupyter icons at 1066 x 1067. Docker's icon was clearly wider, at 1316 x 1126.
File sizes ran from 2,723 bytes to 75,209 bytes, so none of them needed to be heavy.
The safe rule is simple: export a square PNG. A non square icon has to be fitted into a square slot, and you don't control how that looks.
Where PlayMockUp Fits
PlayMockUp makes store images for apps. Its mockup editor frames your screenshots for store listings, and you can use the same images in a README, where they act as your Marketplace gallery. Keep them as PNG or JPG, since SVG fails the check.
For the icon, our app icon size guide covers how to design one mark that holds up at small sizes.
If your extension also ships for browsers, our Chrome Web Store image guide covers that store's icon, screenshot and promo tile sizes.
Frequently asked questions
What size should a VS Code extension icon be?
At least 128 x 128 pixels, as a PNG. Microsoft suggests 256 x 256 for Retina screens, and 19 of the 30 most installed extensions use 256 or larger.
Can a VS Code extension icon be an SVG?
No. vsce won't publish an extension whose icon is an SVG. Export your vector logo to PNG and point the icon field at that file.
How do I add screenshots to the VS Code Marketplace?
Put them in README.md. There's no separate screenshot field, so the README becomes your page body. Each image must load over https and can't be an SVG.
How many keywords can a VS Code extension have?
30. The Marketplace doesn't allow an extension package with more than 30 keywords in package.json, and publishing fails with an error. Pick the words people type, like the language or tool name.
Do browser add-on stores use the same icon rules?
No, each store sets its own sizes and file types, so one icon file rarely fits them all. Our [Firefox add-on guide](/blog/firefox-add-on-icon-screenshot-sizes-2026) covers that store's icon and screenshot sizes.
Build the mockup in your browser.
Drop a screenshot into a real device frame and export at the exact store size — free, no signup.