MarkedUtforskPrøv
Priser
Logg innStart
DesignguidenCSS og nett
CSS og nett

GitHub README banner: a header image for your repo

GitHub never published a README banner size. Choose a frame that can share a ground with your social preview, then export a light file and a dark file.

GradientlyVerifisert Gradiently-konto·19. oktober 2026·7 min lesetid
Omslag: Saffron Abbey · GR·ZVWH·FD

Denne guiden er ikke tilgjengelig på språket ditt ennå, så her er den på engelsk.

Kortversjonen

  • 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.
På denne siden
Sizes people use for a README bannerHow to embed the bannerLight mode and dark modeFile weight and alt textMatch the banner to the social preview

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

1280×640 and the 640×320 floor are the social preview. The wider frames are README conventions, not sizes GitHub publishes.

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.

README banner

Size

No published size

What it actually is

Convention. Any image at the top.
Social preview

Size

1280×640, under 1 MB

What it actually is

Documented. At least 640×320. PNG, JPG or GIF.
Wide header

Size

1600×640

What it actually is

Convention. 2.5:1.
Slim header

Size

1600×400

What it actually is

Convention. 4:1, so the intro stays visible.
README file

Size

Cut off past 500 KiB

What it actually is

Documented. The Markdown, not the image.
AssetSizeWhat it actually is
README bannerNo published sizeConvention. Any image at the top.
Social preview1280×640, under 1 MBDocumented. At least 640×320. PNG, JPG or GIF.
Wide header1600×640Convention. 2.5:1.
Slim header1600×400Convention. 4:1, so the intro stays visible.
README fileCut off past 500 KiBDocumented. The Markdown, not the image.
Social preview size and the 500 KiB cutoff are GitHub's. Banner sizes are choices.

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.

Example project
Keel
A preview for every pull request
Gradiently · @gradiently

A 1600×640 header. The same words go on the social card, with more ground around them.

Example project
Keel
A preview for every pull request
Gradiently · @gradiently

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 ./assets/keel-banner.png. 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.

html
<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>
The quickstart pattern, with relative paths. The alt sits on the img. The light file is the fallback.

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.

Keep the image out of the Markdown

GitHub truncates a README past 500 KiB. That cap is the Markdown, not the PNG, so store the image as its own file.

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
One teal, rebuilt for each theme, then exported as two PNGs. The embed will not paint a CSS background for you.

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. 1

    Write the line once

    Name plus one sentence: that is the banner, the alt, the card and About.

  2. 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. 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. 4

    Export a light file and a dark file

    Same words, two grounds. Commit both PNGs next to the README.

  5. 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.

Design med en levende gradient

Innlegg, stories, lysbilder og bannere i alle størrelser, med tekst som alltid er lesbar.

Begynn å designe, gratis

Spørsmål folk stiller

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.

Del denne guiden

Skrevet av GradientlyVerifisert Gradiently-konto

Teamet bak Gradiently, et designverktøy bygget rundt Marks: levende gradienter som gjør at alt du designer ser ut som ditt.

Se profilen vår

På denne siden

Sizes people use for a README bannerHow to embed the bannerLight mode and dark modeFile weight and alt textMatch the banner to the social preview

Del denne guiden

Neste i CSS og nett

OG image not showing? A checklist to fix your link preview

Les videre

Alle guider om CSS og nett
Sosiale medier

GitHub social preview image: size, safe area and design

7 min lesetid

When someone shares your repo, one small card decides whether they click. Here is the size GitHub wants, where it goes, and how to design it to survive every crop.

Bakgrunner

Design for mørk modus: bakgrunner, farge og kontrast

5 min lesetid

Mørk modus er ikke lys modus med omvendte farger. Flater, tekst, aksenter og gradienter trenger egne verdier, og reglene er annerledes enn dem du kjenner.

Bruksområder

Profilering av åpen kildekode: fra README til versjonsnytt

4 min lesetid

De fleste møter et prosjekt med åpen kildekode gjennom en lenkeforhåndsvisning, en README og et lanseringsinnlegg. Litt profilering på disse tre får prosjektet til å virke vedlikeholdt, pålitelig og verdt en stjerne.

Finn uttrykket som bare er ditt.

Hver Mark er en levende bakgrunn med én eier. Prøv en ledig Mark og sikre deg din når det føles riktig.

Begynn å designeSe lanseringstilbudet

Marks igjen å sikre seg

50av 1 000

950 sikret så langtFinn din

Sjekk et sertifikat

Skriv inn et sertifikatnummer eller en Mark-kode for å se hvem som eier den.

Virker med ChatGPT og Claude

Be AI-en din om et design. Den lager det i din Mark, klart til å redigere.

ChatGPTClaude
Slik kobler du til

Produkt

  • Marked
  • Utforsk
  • Priser
  • Lanseringspakker
  • Sertifikater

Lær

  • Designguiden
  • Hjelpesenter
  • Hva er nytt

Utviklere

  • Oversikt
  • ChatGPT og Claude
  • API-referanse
  • API-nøkler

Selskap

  • Om oss
  • Kontakt oss
  • Logg inn

Juridisk

  • Vilkår
  • Personvern
  • Refusjoner
  • Mark-beskyttelse
  • Informasjonskapsler
  • Alle retningslinjer
Beveg deg over bokstavene. Hver av dem bærer en ekte Mark.Trykk på en bokstav for å se Marken.Ett navn. Ti Marks inni det.
© 2026 Gradiently