MarchéExplorerEssayer
Tarifs
Se connecterCommencer
Guide pratiqueCSS et web
CSS et web

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.

GradientlyCompte Gradiently vérifié·19 octobre 2026·7 min de lecture
Couverture : Saffron Abbey · GR·ZVWH·FD

Ce guide n’est pas encore disponible dans votre langue, le voici donc en anglais.

L’essentiel en bref

  • 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.
Sur cette page
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.

Créez avec un dégradé vivant

Posts, stories, diapositives et bannières dans tous les formats, avec un texte toujours lisible.

Commencer à créer, gratuit

Les questions qu’on nous pose

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.

Partager ce guide

Écrit par GradientlyCompte Gradiently vérifié

L’équipe derrière Gradiently, un outil de création construit autour des Marks : des dégradés vivants qui donnent à tout ce que vous créez votre propre signature.

Voir notre profil

Sur cette page

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

Partager ce guide

À suivre dans CSS et web

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

Pour aller plus loin

Tous les guides : CSS et web
Réseaux sociaux

GitHub social preview image: size, safe area and design

7 min de lecture

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.

Arrière-plans

Design du mode sombre : arrière-plans, couleur et contraste

6 min de lecture

Le mode sombre n’est pas le mode clair inversé. Surfaces, texte, accents et dégradés demandent chacun leurs propres valeurs, et les règles diffèrent de celles que vous connaissez.

Cas d’usage

Branding de projet open source : du README aux releases

6 min de lecture

La plupart des gens découvrent un projet open source par un aperçu de lien, un README et un post de release. Un peu de branding sur ces trois points donne l’image d’un projet suivi, fiable et digne d’une étoile.

Trouvez le style qui n’est qu’à vous.

Chaque Mark est un fond vivant avec un seul propriétaire. Essayez un Mark encore disponible et réservez le vôtre quand vous le sentez.

Commencer à créerVoir l’offre de lancement

Marks encore à réserver

50sur 1 000

950 réservés à ce jourTrouver le vôtre

Vérifier un certificat

Saisissez un numéro de certificat ou le code d’un Mark pour voir à qui il appartient.

Fonctionne avec ChatGPT et Claude

Demandez une création à votre IA. Elle la réalise dans votre Mark, prête à modifier.

ChatGPTClaude
Comment se connecter

Produit

  • Marché
  • Explorer
  • Tarifs
  • Packs de lancement
  • Certificats

Apprendre

  • Guide pratique
  • Centre d’aide
  • Nouveautés

Développeurs

  • Vue d’ensemble
  • ChatGPT et Claude
  • Référence de l’API
  • Clés API

Entreprise

  • À propos
  • Nous contacter
  • Se connecter

Mentions légales

  • Conditions
  • Confidentialité
  • Remboursements
  • Protection des Marks
  • Cookies
  • Toutes les politiques
Parcourez les lettres. Chacune porte un vrai Mark.Touchez une lettre pour voir son Mark.Un seul nom. Dix Marks à l’intérieur.
© 2026 Gradiently