MercadoExplorarExperimentar
Preços
Iniciar sessãoComeçar
Guia PráticoCSS e web
CSS e 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.

GradientlyConta Gradiently verificada·19 de outubro de 2026·7 min de leitura
Capa: Saffron Abbey · GR·ZVWH·FD

Este guia ainda não está disponível no teu idioma, por isso aqui está em inglês.

A versão curta

  • 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.
Nesta página
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.

Cria com um gradiente vivo

Publicações, stories, diapositivos e banners em todos os tamanhos, com texto que se lê sempre.

Começar a criar, grátis

Perguntas frequentes

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.

Partilhar este guia

Escrito pela GradientlyConta Gradiently verificada

A equipa por trás da Gradiently, uma ferramenta de design construída em torno dos Marks: gradientes vivos que fazem tudo o que crias parecer teu.

Ver o nosso perfil

Nesta página

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

Partilhar este guia

A seguir em CSS e web

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

Continua a ler

Todos os guias de CSS e web
Redes sociais

GitHub social preview image: size, safe area and design

7 min de leitura

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.

Fundos

Design em modo escuro: fundos, cor e contraste

6 min de leitura

O modo escuro não é o modo claro invertido. Superfícies, texto, acentos e gradientes precisam de valores próprios, e as regras são diferentes das que já conheces.

Casos de uso

Branding de projeto open source: do README às notas de versão

6 min de leitura

A maioria das pessoas conhece um projeto open source através da pré-visualização de uma ligação, de um README e de uma publicação de versão. Um pouco de branding nestes três faz um projeto parecer cuidado, de confiança e merecedor de uma estrela.

Encontra o visual que é só teu.

Cada Mark é um fundo vivo com um só dono. Experimenta um Mark ainda disponível e reserva o teu quando te parecer certo.

Começar a criarVer a oferta de lançamento

Marks por reservar

50de 1000

950 reservados até agoraEncontra o teu

Verificar um certificado

Escreve um número de certificado ou o código de um Mark para veres quem é o dono.

Funciona com o ChatGPT e o Claude

Pede um design à tua IA. Ela cria-o no teu Mark, pronto a editar.

ChatGPTClaude
Como ligar

Produto

  • Mercado
  • Explorar
  • Preços
  • Pacotes de lançamento
  • Certificados

Aprender

  • Guia Prático
  • Centro de ajuda
  • Novidades

Programadores

  • Visão geral
  • ChatGPT e Claude
  • Referência da API
  • Chaves de API

Empresa

  • Sobre nós
  • Contactos
  • Iniciar sessão

Legal

  • Termos
  • Privacidade
  • Reembolsos
  • Proteção de Marks
  • Cookies
  • Todas as políticas
Passa pelas letras. Cada uma veste um Mark real.Toca numa letra para veres o seu Mark.Um nome. Dez Marks lá dentro.
© 2026 Gradiently