# GitHub social preview image: size, safe area and design

[Canonical HTML page](https://gradiently.design/guide/github-social-preview)

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.

## The short version

- The GitHub social preview image should be 1280×640 pixels, with a minimum of 640×320 and a file under 1 MB in PNG, JPG or GIF.
- You upload a repository's social preview in Settings, on the General page, under Social preview.
- GitHub publishes the social preview as the repository page's Open Graph image, so X, LinkedIn, Slack and chat apps all use it.
- A good social preview shows only the project name, one line about what it does, and a solid or gradient ground, with the name inside the centre square.
- If an old preview still appears after you upload a new one, the sharing platform has cached it, and a fresh fetch or a new URL fixes it.

A **GitHub social preview** is the image people see when your repository link is shared on X, LinkedIn, Slack, Discord or in a chat. GitHub asks for a PNG, JPG or GIF **under 1 MB**, at least **640×320 pixels**, and recommends **1280×640** for the best display. You upload it in the repository's **Settings › General › Social preview**, and GitHub then serves it as the repo's Open Graph image.

- GitHub social preview 1280×640: 1280 × 640
- Minimum 640×320: 640 × 320
- Open Graph 1200×630: 1200 × 630

The recommended size, the minimum GitHub accepts, and the standard Open Graph card. GitHub's image is a clean 2:1; Open Graph is about 1.91:1.

## GitHub social preview size and file rules

Design at 1280×640. It is exactly 2:1, which matches the large card on X and sits close to the 1.91:1 card most other platforms draw. Treat 640×320 as a floor: it looks soft on high density screens.

| Rule | Value | Why it matters |
| --- | --- | --- |
| Recommended size | 1280×640 px | Sharp on high density screens, exact 2:1 ratio |
| Minimum size | 640×320 px | Anything smaller is rejected or looks blurry |
| File types | PNG, JPG or GIF | Use PNG for type and flat colour, JPG for photos |
| File weight | Under 1 MB | GitHub refuses larger uploads |
| Transparency | Supported in PNG | Risky: the card colour behind it changes per app and per theme |
| Who sees it | Public repositories | Private repos only keep an image uploaded earlier |

GitHub's documented rules for the repository social preview, with the reason each one matters in practice.

A designed card with a gradient ground and a few words comes in well under 1 MB as a PNG. If yours does not, it is usually a photo or heavy noise layer; [image compression](https://gradiently.design/guide/image-compression) and [PNG vs JPEG](https://gradiently.design/guide/png-vs-jpeg) cover how to bring it down without visible damage.

> **Skip the transparent PNG** GitHub accepts transparency, but the card behind your image is white in one app, near black in another, and flips with dark mode. A transparent logo that reads on one disappears on the other. Give the image its own solid or gradient ground.

## Where to upload a social preview on GitHub

1. **Open the repository settings** Go to the repository's main page and click **Settings**. If the tab is hidden, open the **…** menu at the end of the tab row.
2. **Find Social preview** On the **General** page, scroll to **Social preview**. Without an image, GitHub shows a generated card with the repo's name, description, a few stats and the owner's avatar.
3. **Upload the image** Click **Edit**, then **Upload an image…**, and choose your 1280×640 PNG.
4. **Test a fresh share** Paste the repo URL into a new post or chat. If you see the old card, that platform has cached it; see the section on updates below.

To go back to GitHub's generated card, use **Edit › Remove image** in the same place.

## Safe area: what survives every crop

GitHub does not publish a safe area, but the platforms that show your image do crop it. A 2:1 image shown in a 1.91:1 card loses roughly 30 pixels from each side. Some chat apps and mobile layouts crop link images to a square from the centre, which leaves only the middle 640×640. And everything gets small: in a feed the whole card is often a few hundred pixels wide.

- Full image 1280×640: 1280 × 640
- 1.91:1 card 1220×640: 1220 × 640
- Centre square 640×640: 640 × 640

The full upload, what remains in a standard 1.91:1 link card, and the centre square some apps keep. Put the repo name inside the square.

- **Margins of at least 64 px** on every edge, so nothing touches a crop or a rounded corner.
- **The project name inside the centre 640×640**, so a square crop still says what it is.
- **Type tall enough to read small:** a name around 96 to 140 px and a line around 40 to 56 px on the 1280×640 canvas.
- **Nothing important in the corners**, where cards round off and some apps overlay a play or site badge.

## What to show on a GitHub social preview

Three things, and nothing more: the **project name**, **one line** that says what it does, and a **ground** that is recognisably yours. The card already shows the URL, so skip the owner, star counts and feature lists. Code screenshots turn to grey noise at card size.

A 1280 by 640 GitHub social preview reading Tidewater with a short description line on a gradient

Name and one line on a calm ground: it reads at feed size and survives a square crop.

A 1280 by 640 GitHub social preview with the single word Tidewater large on a gradient

The same project with only its name: bolder, but the card has to explain what it does.

### Avoid

- A screenshot of the README or the code
- Star counts and badges that go stale
- The logo alone on a transparent background
- Small text near the edges
- A different look from your site and docs

### Do

- The project name, large and centred
- One line in plain words: what it does
- A solid or gradient ground that works in light and dark apps
- 64 px margins and the name inside the centre square
- The same ground as your README banner and site

Share one ground across the README banner, docs and social preview so a shared link looks like the project people met on GitHub. [Open source project branding](https://gradiently.design/guide/open-source-project-branding) covers building that small system around one ground.

## Why your GitHub social preview doesn't update

GitHub switches the image on the repository page as soon as you upload it. The old card you still see elsewhere is a cache: X, LinkedIn, Slack, Discord and messaging apps fetch a link's preview once and reuse it, sometimes for days. Old posts keep their old card for good.

- **LinkedIn:** paste the repo URL into the [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/) to fetch it again.
- **Everywhere else:** share a URL the platform has not seen, such as the repo link with a harmless query on the end (`?v=2`). It is a new address to the crawler, so it fetches a fresh preview.
- **Check GitHub first:** open the repo in a private window and confirm Settings shows the new image. If it does, the problem is the platform's cache, not your upload.
- **Still blank?** The repository may be private; GitHub only shares social previews for public repos.

The same fixes apply to any site's link previews. [OG image not showing](https://gradiently.design/guide/og-image-not-showing) is the full checklist.

## How the social preview relates to OG images

The social preview *is* an Open Graph image. GitHub writes it into the repo page's `og:image` tag, with a large card setting for X, so every platform reads it the same way it reads yours. You cannot edit those tags on github.com, which is why the upload exists.

```html
<!-- Roughly what GitHub serves in the head of a public repo page -->
<meta property="og:title" content="tidewater-dev/tidewater" />
<meta property="og:description" content="Fast diffing for large JSON files." />
<meta property="og:image" content="https://repository-images.githubusercontent.com/..." />
<meta property="og:url" content="https://github.com/tidewater-dev/tidewater" />
<meta name="twitter:card" content="summary_large_image" />
```

The tags a crawler reads from a repository page. Your uploaded image becomes the og:image; the description comes from the repo's About field.

For your project's own website, you set these tags yourself, usually with a 1200×630 image. Design the two as a pair: same ground, same name, same line, at 1280×640 for GitHub and 1200×630 for the site. With good margins, one layout fits both. [OG image size](https://gradiently.design/guide/open-graph-image-size) and [Open Graph tags](https://gradiently.design/guide/open-graph-tags) cover the site side, and [dynamic OG images](https://gradiently.design/guide/dynamic-og-images) shows how to generate one per docs page.

## Make a GitHub social preview in Gradiently

In the Studio, start a design at a **custom size of 1280×640** and pick a Mark as the ground. Set the project name and one line; the Mark keeps its calmest region behind the words and Auto ink picks light or dark type from its palette, so it reads in both light and dark apps. Export as **PNG** and upload it in Social preview. For the matching site card, add the built-in Link preview (Open Graph) 1200×630 size to the same design so both share one ground.

A 1200 by 630 link preview card reading Tidewater on the same gradient as the GitHub social preview

The site's 1200×630 Open Graph card cut from the same design as the GitHub image, so the repo and the site share one look.

## FAQ

### What size is the GitHub social preview image?

GitHub recommends 1280×640 pixels and requires at least 640×320. The file must be a PNG, JPG or GIF under 1 MB.

### Where do I change the social preview on GitHub?

Open the repository, click Settings, and on the General page find Social preview. Click Edit, then Upload an image.

### Why is my GitHub social preview not updating?

The platform you shared on has cached the old card. Refresh it with a tool like LinkedIn Post Inspector, or share the URL with a query such as ?v=2 so it is fetched fresh.

### Can I use a transparent PNG for a GitHub social preview?

GitHub accepts it, but the card behind it changes colour between apps and with dark mode, so a solid or gradient background is safer.

### Is the GitHub social preview the same as an OG image?

Yes. GitHub puts your uploaded image in the repository page's og:image tag, which is what every platform reads for link previews.