The short version
- GitHub publishes no README banner size. The image scales to the column, so the ratio sets the header height.
- A useful convention is 1280×640, the frame GitHub recommends for the social preview, or a wider 1600×640, or a slimmer 1600×400.
- Embed one image with Markdown. For light and dark mode, use a picture element with prefers-color-scheme and one file per theme.
- Keep each file under 1 MB if it may also be the social preview, and put the banner's words in the alt when the README does not repeat them.
- The banner is not the link card. Upload a separate 1280×640 image under Social preview, with the same ground, name and line.
On this page
A GitHub README banner is the wide image at the top of a repository README. GitHub publishes no width or height for it. The useful conventions are 1280×640, the social preview frame, a wider 1600×640, and a slimmer 1600×400.
One file is a Markdown image: an exclamation mark, the alt in brackets, then the path in parentheses, with nothing between them. Two themes need the HTML below. The shared-link card is a different upload, and it should use the same name, line and ground.
Social card 1280×640
1280 × 640
Wide header 1600×640
1600 × 640
Slim header 1600×400
1600 × 400
Preview minimum 640×320
640 × 320
Sizes people use for a README banner
GitHub scales the image down to the column and does not crop it to a slot. A 2:1 image ends up half as tall as the column is wide. A 2.5:1 image is shorter, and a 4:1 image is about half the height of the 2:1. Extra pixels keep type sharp on a high density screen. They do not make the banner bigger.
Size
What it actually is
Size
What it actually is
Size
What it actually is
Size
What it actually is
Size
What it actually is
Use 1280×640 when one layout should do both jobs. GitHub recommends it for the social preview, with 640×320 as the floor, and on the repo page that ratio is a tall header. Use 1600×640 for a wider ground, or 1600×400 when the image is only a signature. Around 1280 to 1600 px wide is enough.
A 1600×640 header. The same words go on the social card, with more ground around them.
The same words at 1280×640, kept out of the corners a shared card often crops.
- The name, still readable after the column shrinks the image.
- One line about what it does, repeated in About.
- One ground for the card, the docs and the site.
- The name in the middle, clear of the crop.
- No stale numbers. Stars and versions go under the image, in Markdown.
How to embed the banner
Commit a PNG beside the README and use a relative path. GitHub rewrites it for the current branch. A path starting with / is from the repo root. For the fictional project Keel, the file is ./. Markdown sets no width, so the column scales it. The alt is the banner's own words.
Markdown cannot swap files by theme. GitHub's writing quickstart uses the HTML picture element: a dark source, a light source, and an img for when picture is ignored. The test is prefers-color-scheme. GitHub's dark theme matches the dark value, and the browser downloads only the source that matches.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/keel-banner-dark.png">
<source media="(prefers-color-scheme: light)" srcset="./assets/keel-banner-light.png">
<img alt="Keel: a preview for every pull request." src="./assets/keel-banner-light.png">
</picture>Leave a blank line before and after the picture, so Markdown treats it as HTML. Both files must say the same thing, because there is only one alt. Point src at the light file so a renderer that skips picture still shows a banner.
GitHub also honours #gh-dark-mode-only and #gh-light-mode-only, added in November 2021. They work only on GitHub. Prefer picture, and keep both images on one line if you use the fragments.
Light mode and dark mode
An opaque banner brings its own ground. The miss is a bright slab on a dark README, or a dark slab on a light one. Export twice: a deeper ground and light type for dark mode, the reverse for light mode, same words. Do not invert the file. A calm colour can turn harsh. See dark mode design and contrast.
Avoid
- One white banner for both themes
- A black wordmark with no light twin
- An inverted copy of the light file
- Different lines on the two files
Do
- The same words on both files
- A light ground and a dark ground
- Dark type on light, light type on dark
- One alt that is true for both
Or use a wordmark with no ground: dark letters for light mode, light letters for dark mode, on a clear background so the page colour shows through. Keep a solid ground on the social card. Wordmarks covers the lettering.
File weight and alt text
GitHub sets no byte limit on a README banner. It warns above 50 MiB, blocks a file over 100 MiB, and stops a browser upload at 25 MiB. Stay far under those. The social preview should be under 1 MB, so keep each banner under 1 MB too.
Use PNG for type on a flat or gradient ground, and JPG for a photo. The social preview accepts PNG, JPG or GIF, not SVG. A relative SVG can show in the README, but it cannot be that upload. See PNG vs JPG, SVG vs PNG and image compression.
Alt is a short equivalent of the image, on the img only. If the tagline is only on the banner, the alt is the name plus that line. If the heading repeats both, leave it empty. Do not write "banner". WebAIM's alt text guide is the rule, and the one alt must stay true for both files.
Match the banner to the social preview
The banner is what you embed. Upload the social preview in Settings, under Social preview, then Edit and Upload an image. GitHub asks for PNG, JPG or GIF under 1 MB, at least 640×320, and 1280×640 for the best display. Only a public repo shares it. Transparency is allowed, but app backgrounds differ, so use an opaque ground. Crops and stale cards are covered in GitHub social preview.
- 1
Write the line once
Name plus one sentence: that is the banner, the alt, the card and About.
- 2
Design the 1280×640 card first
Put the name in the centre, with a margin. Apps crop the sides, and some keep the middle square.
- 3
Make the README frame from the same ground
Keep 1280×640, or move to 1600×640 or 1600×400. Export again. Do not squash the card.
- 4
Export a light file and a dark file
Same words, two grounds. Commit both PNGs next to the README.
- 5
Embed, then upload the card
Paste the HTML and toggle the theme. Then upload the opaque 1280×640 PNG under Social preview.
Use one ground everywhere the project appears. Open source project branding is the wider system. The banner is only the piece above the install steps.
You can build both frames in Gradiently. Start a blank design at a custom size, from 200 to 8,000 px, on a Mark. It moves a calm area behind the type, and Auto ink picks light or dark letters from its palette. Export a PNG per theme and a 1280×640 card. A transparent PNG drops the Mark, is part of Pro, and still needs one file per theme. See exporting SVG and transparent PNG.
Questions people ask
What size is a GitHub README banner?
GitHub publishes none. Conventions that work are 1280×640, a wider 1600×640, or a slimmer 1600×400 so the introduction stays on screen.
How do I add a banner image to a README?
Commit a PNG and embed it with Markdown, or with a picture element when you have a light file and a dark file. Use a relative path so the image follows the branch.
How do I make a README banner work in dark mode?
Export the same layout twice, one light ground and one dark ground, and switch them with picture and prefers-color-scheme. A single black wordmark on a clear background disappears in dark mode.
Does the README banner show when I share the repo?
No. The shared card is the social preview, uploaded under Settings, then Social preview. GitHub recommends 1280×640 as a PNG, JPG or GIF under 1 MB, and only a public repo shares it.
What alt text should a README banner use?
Use the name and the line on the image when the README does not already say them. If the heading repeats both, leave the alt empty so a screen reader does not announce them twice.
How big should the banner file be?
No README-specific limit. Keep each file under 1 MB so it can also be the social preview, and store it outside the Markdown, which GitHub cuts past 500 KiB.
Written by Gradiently
The team behind Gradiently, a design tool built around Marks: living gradients that make everything you design look like yours.
See our profile