Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
A GitHub Open Graph image is the Social preview graphic GitHub displays when someone shares a repository link on a social platform. To add one, open the repository, choose Settings → Social preview → Edit, upload a PNG, JPG, or GIF under 1 MB, and save it. GitHub recommends at least 640 × 320 pixels and suggests 1280 × 640 pixels for the best display.
If you do not set a custom image, GitHub says the link preview shows basic repository information and the owner’s avatar. The image can be uploaded for a public repository, or for a private repository that previously had an image uploaded, but it can only be shared from a public repository.
What a GitHub Open Graph image does
When a repository URL is posted to a platform that reads Open Graph metadata, the platform can generate a preview card. GitHub calls the repository-level setting Social preview. The custom graphic becomes the visual representation of that repository link; it is not a file committed to the repository and it does not change the repository’s README.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Without a custom preview, GitHub’s documented fallback is basic repository information and the owner’s avatar. That fallback explains why a shared repository may show a profile picture instead of project artwork.
#1 Best Overall
GitHub’s GraphQL reference exposes the image state through openGraphImageUrl, which contains the image URL used for Open Graph data, and usesCustomOpenGraphImage, which indicates whether the repository is using a custom image rather than the owner’s avatar. These API fields describe repository state; they do not replace the Settings interface used to upload the file.
See GitHub’s Social preview documentation for the current interface and rules.
How to add a social preview image
- Open the repository’s main page. You need the repository’s settings permissions. If the Settings tab is not visible, GitHub says it may be inside the tab’s dropdown menu.
- Open Settings. In the repository navigation, select Settings.
- Find Social preview. In the settings page, locate the Social preview section.
- Select Edit. Use Edit to open the upload controls.
- Upload the file. Choose a PNG, JPG, or GIF that is under 1 MB. For reliable sizing, prepare it at 1280 × 640 pixels; GitHub’s recommended minimum is 640 × 320.
- Save the change. Return to the repository page and share its URL to check how the preview is generated. A social platform may cache an earlier card, so a change may not appear immediately everywhere.
The control is repository-specific. Setting a preview on one repository does not set it for other repositories in the account or organization.
How to remove or replace the image
Replace the current image
Repeat Settings → Social preview → Edit, upload the replacement, and save. Keep the replacement within GitHub’s format and size guidance. Replacing the image preserves the repository’s custom-preview status while changing the artwork shown for future link expansions.
Remove the custom image
Open the same Social preview editor and choose GitHub’s remove-image action. After removal, the repository returns to GitHub’s documented fallback: basic repository information and the owner’s avatar.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
File requirements at a glance
| Item | GitHub guidance | What it means in practice |
|---|---|---|
| Accepted formats | PNG, JPG, or GIF | Export in one of these formats before uploading. |
| Maximum file size | Under 1 MB | A file at exactly 1 MB does not satisfy the stated “under 1 MB” guidance; compress or resize it. |
| Recommended minimum | 640 × 320 pixels | Smaller artwork is below GitHub’s recommendation and may provide less usable detail. |
| Suggested size for best display | 1280 × 640 pixels | This 2:1 canvas gives text and visual elements room to remain clear when scaled. |
| Transparency | Supported for PNG | Transparent artwork can work on services that support dark mode, but its appearance varies by background and platform. |
These are technical constraints and recommendations from GitHub, not measured engagement or click-through statistics. GitHub does not promise identical rendering on every social service.
Designing an image that survives preview scaling
Keep the message short
Social cards are often displayed much smaller than the source file. Use a brief repository name or purpose, a recognizable logo or illustration, and strong contrast. This is practical design guidance, not a GitHub requirement. Avoid placing essential words at the extreme edges, where different platforms may crop or pad the card.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose a background deliberately
GitHub supports transparent PNG files and notes that transparency can be useful on communication platforms with dark mode. The same transparency may look unexpected on a colored background or on a service that does not support it. When you cannot predict the sharing destinations, GitHub’s safe recommendation is a solid background.
Check the file before upload
- Confirm the extension is PNG, JPG, or GIF.
- Check the dimensions: at least 640 × 320; 1280 × 640 is the suggested target.
- Check the file size is below 1 MB.
- Open the exported file on both a light and dark background if it uses transparency.
- Reduce small text and fine lines that disappear when the card is rendered at a few hundred pixels wide.
Public and private repository behavior
GitHub’s documentation allows an image to be uploaded to a public repository. It also documents uploading to a private repository when an image had previously been uploaded. That private-repository condition does not make the image publicly shareable: GitHub states that the image can only be shared from a public repository.
If a private project’s link must remain private, do not treat a Social preview image as a way to publish it. Access controls and the visibility of the repository still determine who can retrieve and share the repository content.
Rank #3
Checking preview state with GraphQL
For an API consumer, the relevant repository fields in GitHub’s GraphQL reference are openGraphImageUrl and usesCustomOpenGraphImage. The first identifies the URL used for Open Graph data; the second distinguishes a custom image from the avatar fallback.
Use usesCustomOpenGraphImage when your automation needs a yes/no state, and use openGraphImageUrl when it needs the image URL. Treat these fields as read state: the documented upload and removal workflow remains the repository’s Settings → Social preview interface. The field definitions are in GitHub’s repository GraphQL reference.
Troubleshooting common problems
The Social preview section is missing
First verify that you opened the repository’s own Settings, not your account settings. GitHub says the Settings tab may be in a dropdown menu, so expand the repository navigation if it is not shown directly. You also need sufficient repository permissions to change the setting.
The upload is rejected
Check all three documented constraints: the file must be PNG, JPG, or GIF; it must be under 1 MB; and it should be at least 640 × 320 pixels. Exporting a large PNG as an optimized JPG can reduce size, but do not change to an unsupported format.
The old image still appears when a link is shared
Social platforms commonly cache link metadata. Confirm that the new image is saved in GitHub’s Social preview editor, then allow the sharing service to refresh its cached card. Test with a newly composed post rather than relying on an already-rendered message.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
The repository shows an avatar instead of the artwork
That is GitHub’s documented fallback when no custom Social preview image is set. Return to Settings → Social preview → Edit and upload an image, or use the GraphQL usesCustomOpenGraphImage field to check whether a custom image is active.
The transparent image looks wrong
Transparency is supported for PNG, but GitHub warns that the result can differ on colored backgrounds and services without transparency support. Add a solid background when the destination platforms are unknown.
A private repository’s image cannot be shared
This is expected under GitHub’s stated rule: the private-repository upload condition does not make the image publicly shareable. Public sharing requires a public repository.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
When your workflow needs an actual screenshot of a repository or other web page rather than GitHub’s Social preview metadata, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
For a direct capture, see the full parameter list in the ScreenshotNeo documentation:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://github.com/OWNER/REPOSITORY -o shot.webpThe same endpoint supports full-page capture, lazy-image loading, CSS-selector element capture, dark mode, device presets, arbitrary viewports, retina scale, PDF paper and margin options, custom CSS and JavaScript, clicks before capture, selector hiding, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.
Pricing includes 1,000 screenshots each month on the free plan with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Create a free ScreenshotNeo account to try it without a card.
Recommended Free Tools
Practical checklist
- Open the repository’s Settings → Social preview area.
- Use PNG, JPG, or GIF under 1 MB.
- Prepare at least 640 × 320 pixels; target 1280 × 640 pixels.
- Use readable contrast and a recognizable visual at small sizes.
- Choose a solid background if transparency may render unpredictably.
- Remember that a private repository’s image cannot be publicly shared.
- Expect social platforms to cache old previews after an update.
- Use
openGraphImageUrlandusesCustomOpenGraphImagewhen checking state through GraphQL.
Frequently Asked Questions
Is a GitHub Social preview image the same as a repository README image?
No. Social preview is repository metadata used for link cards; it is configured in repository Settings and is separate from files displayed in the README.
Can I use an animated GIF?
GitHub lists GIF as an accepted upload format. How a particular social platform animates or renders that GIF is controlled by the platform, not guaranteed by GitHub.
Does GitHub provide click-through performance data for these images?
The documented guidance covers formats, dimensions, size, and transparency. It does not establish engagement or click-through statistics.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
