To add a social preview image to a GitHub repository, prepare a PNG, JPG, or GIF smaller than 1 MB, ideally at 1280 × 640 pixels, then upload it from the repository’s Settings page under Social preview. GitHub recommends at least 640 × 320 pixels and supports transparent PNGs, although a solid background is safer when you do not know how a sharing platform handles transparency.
What a GitHub social preview image does
GitHub calls this the repository’s “social media preview” or “Social preview.” It is the image displayed on social media platforms when someone links to your repository. The image is attached to the repository through GitHub settings; it is not a file that you commit to the repository.
A repository owner can change the image, replace it, or remove it. A preview image can be uploaded to a public repository, or to a private repository where an image was previously uploaded, but GitHub allows it to be shared from a public repository only.
The preview is separate from your repository avatar, README images, release assets, and website screenshots. Treat it as a small, self-contained introduction to the project: include the project name, a short benefit or description, and enough contrast that the image remains readable when shown at a reduced size.
#1 Best Overall
- All-in-One Convenience - Print and Cut in One Step. Say goodbye to the hassle of using separate machines. The PixCut S1 seamlessly integrates high-resolution photo printing and precise die cutting into one streamlined device. With just a few clicks on the user-friendly app, you can edit, print, and cut directly from your smartphone via Bluetooth. Create stickers in just 2 minutes! The Inspire Kit includes 36 photo papers and 144 sticker papers, so you can create endlessly without running out.
- AI Image Extraction & Precision Cutting - Unleash your creativity with the AI image extraction feature that automatically recognizes and extracts subjects from your photos. Then watch as the precision cutting system, guided by the same AI technology, perfectly follows every edge with pinpoint accuracy. This seamless workflow ensures flawless results every time. Turn countless moments into custom stickers with the generous paper bundle—professional edges made simple.
- High-Resolution Prints - Vivid and True-to-Life Colors. Utilizing thermal dye-sublimation technology, the PixCut S1 delivers stunning 300 dpi high-resolution prints with 16.7 million colors. Whether you're printing photos, stickers, or labels, you can expect vibrant, true-to-life color effects that make your creations stand out. With the Inspire Kit’s abundant paper supply, you’re ready to print vivid memories and labels whenever inspiration strikes.
- AI Lab - Bring Your Imagination to Life. Upload a photo, pick a style from the Liene Photo App, and watch AI bring your vision to life instantly. Turn selfies into an anime character, a fantasy hero, or a festive holiday illustration — all with stunning realism. One style, endless versions of you. Print your AI art as custom stickers, unique gifts, or social media posts — perfect for avatars and DIY projects. No design experience required. Your creativity is just one click away from magic.
- Durable Stickers - Create Long-Lasting Creations .Thanks to the four-layer thermal dye-sublimation technology, the photopaper is automatically laminated during printing. Stickers produced by PixCut S1 are durable, waterproof and scratch-resistant, ensuring they remain vibrant and intactover time. Perfect for creating custom stickers, labels, and more that last.
Image requirements and recommended size
Before opening GitHub, export the artwork in one of the formats GitHub accepts and check its dimensions and file size.
| Item | GitHub guidance | Practical choice |
|---|---|---|
| Formats | PNG, JPG, or GIF | Use PNG for sharp text or transparency; use JPG for photographic artwork; use GIF only when an animated or indexed image is specifically needed. |
| Maximum file size | Under 1 MB | Check the final exported file, not just the source design file. |
| Minimum recommended dimensions | At least 640 × 320 pixels | Do not design below this size if the image will be shared. |
| Best-display recommendation | 1280 × 640 pixels | Start with a 2:1 canvas at 1280 × 640 and keep important text away from the edges. |
| Transparency | Transparent PNGs are supported | Preview the artwork on light, dark, and colored backgrounds; choose a solid background if the destination platforms are unknown. |
The 640 × 320 and 1280 × 640 figures are current recommendations in GitHub’s documentation, not a guarantee that every social network will crop or scale the image identically. Third-party platforms may apply their own preview treatment.
Choose a background deliberately
A transparent PNG can blend into the page behind it. That may look excellent in one app and low-contrast in another, especially when users switch between light and dark modes. A solid background gives you predictable contrast and is the safer default when you cannot test every destination.
Keep the design legible at thumbnail size
- Use one clear title instead of a paragraph of copy.
- Make the project name the strongest visual element.
- Use high contrast between text and background.
- Leave breathing room around logos, icons, and text so edge cropping does not remove meaning.
- Export the final artwork and confirm that it remains below 1 MB.
How to upload a social preview in GitHub
- Open the repository’s main page.
- Under the repository name, select Settings. If Settings is not visible as a tab, open the tab dropdown and choose it.
- In the settings navigation, find the Social preview section.
- Select Edit.
- Choose Upload an image, select your PNG, JPG, or GIF file, and complete the upload.
- Return to the repository page or settings view and confirm that the new artwork appears in the Social preview area.
To replace an existing preview, upload the replacement from the same section. To clear it, choose Remove image. GitHub can change navigation labels or placement over time, but the current workflow is repository page → Settings → Social preview → Edit.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Creating the image: two dependable workflows
Design a purpose-built repository card
- Create a 1280 × 640 document in the image editor of your choice.
- Add the repository or project name and a concise description of what it does.
- Use a background color or illustration that maintains contrast in both light and dark viewing contexts.
- Keep key elements inside a safe margin rather than touching the canvas edges.
- Export as PNG, JPG, or GIF and verify that the exported file is under 1 MB.
- Upload the exported file through GitHub’s Social preview settings.
This approach gives you control over branding and typography. It is usually better than using an unedited screenshot because a screenshot may contain browser chrome, cookie notices, chat bubbles, or transient page content.
Capture a webpage as the starting artwork
- Open the page you want to represent in a browser and wait until the visible content has finished loading.
- Dismiss consent notices, newsletter prompts, and chat widgets before capturing, so they do not cover the content.
- Capture the page or the specific section that explains the project.
- Crop the result to a 2:1 composition, add a title or brand treatment, and ensure the final export meets GitHub’s format and size limits.
- Check the image at thumbnail size and against both light and dark backgrounds.
- Upload the finished image in repository Settings under Social preview.
A raw browser capture is rarely a finished social card. It may include dynamic content, overlays, or a viewport ratio that does not fit GitHub’s recommendation. Treat it as source material and edit it before uploading.
Or skip the browser setup
ScreenshotNeo is the first option to try when you want an automated webpage capture: it removes cookie banners, newsletter popups, and chat widgets before the shot, and only clean captures are billed.
One GET request returns a PNG, JPEG, WebP, or PDF. Replace the example URL with the public page you want to turn into source artwork. Full documentation, including all parameters, is at https://screenshotneo.com/docs/.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://github.com/your-owner/your-repository -o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={
"access_key": "YOUR_API_KEY",
"url": "https://github.com/your-owner/your-repository",
},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://github.com/your-owner/your-repository'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));After downloading the image, crop or redesign it to 1280 × 640 (or at least 640 × 320), add any required title treatment, and export a PNG, JPG, or GIF under 1 MB before uploading to GitHub.
Automation options that matter for a repository card
ScreenshotNeo supports full-page capture with lazy images loaded, a single element selected by CSS selector, dark mode, 12 device presets plus custom viewports, retina scale, image resizing, custom CSS and JavaScript, clicking an element before capture, hiding selectors, and waiting for a selector, a delay, or network idle. You can block ads, trackers, requests, or resource types; provide custom headers, cookies, a user agent, or Authorization; set timezone and geolocation; use a transparent background; choose caching with your own TTL; create signed links for public <img> tags; submit asynchronous jobs with signed webhooks; capture up to 100 URLs per bulk call; and query usage through the usage API. It also provides an OpenAPI specification, and parameter names used by other screenshot APIs work for easier migration.
For AI-assisted workflows, its MCP server exposes take_screenshot, get_page_info, and capture_pdf tools to Claude, Cursor, and other MCP clients. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; responses identify the result with X-Page-Verdict and X-Billed headers.
Rank #3
- All-in-One Convenience - Print and Cut in One Step. Say goodbye to the hassle of using separate machines. The PixCut S1 seamlessly integrates high-resolution photo printing and precise die cutting into one streamlined device. With just a few clicks on the user-friendly app, you can edit, print, and cut directly from your smartphone via Bluetooth. Create stickers in just 2 minutes! This all-in-one solution saves you time and effort, making your creative projects more enjoyable and efficient.
- AI Image Extraction & Precision Cutting - Unleash your creativity with the AI image extraction feature that automatically recognizes and extracts subjects from your photos. Then watch as the high-precision cutting system, guided by the same AI technology, perfectly follows every edge with pinpoint accuracy. This seamless AI-to-cut workflow ensures flawless results every time. Turn any moment into custom stickers with professional edges in minutes - just masterpieces made simple.
- High-Resolution Prints - Vivid and True-to-Life Colors. Utilizing thermal dye-sublimation technology, the PixCut S1 delivers stunning 300 dpi high-resolution prints with 16.7 million colors. Whether you're printing photos, stickers, or labels, you can expect vibrant, true-to-life color effects that make your creations stand out. Every detail is captured with precision, providing professional-quality results every time.
- AI Lab - Bring Your Imagination to Life. Upload a photo, pick a style from the Liene Photo App, and watch AI bring your vision to life instantly. Turn selfies into an anime character, a fantasy hero, or a festive holiday illustration — all with stunning realism. One style, endless versions of you. Print your AI art as custom stickers, unique gifts, or social media posts — perfect for avatars and DIY projects. No design experience required. Your creativity is just one click away from magic.
- Durable Stickers - Create Long-Lasting Creations .Thanks to the four-layer thermal dye-sublimation technology, the photopaper is automatically laminated during printing. Stickers produced by PixCut S1 are durable, waterproof, fade-resistant,and scratch-resistant, ensuring they remain vibrant and intactover time. The easy-peel backing makes application a breeze, leaving no adhesive residue and allowing for repositioning. Perfect for creating custom stickers, labels, and more that last.
Plans
| Plan | Allowance | Price |
|---|---|---|
| Free | 1,000 shots per month | Free, no card |
| Starter | 3,000 shots | $5 |
| Growth | 15,000 shots | $15 |
| Pro | 60,000 shots | $39 |
| Scale | 250,000 shots | $99 |
| Business | 1,000,000 shots | $249 |
Yearly billing gives two months free, and every feature is included on every plan. Create a free ScreenshotNeo account to use 1,000 screenshots a month without a card.
Recommended Free Tools
Testing the preview after upload
GitHub’s setting confirms that an image is attached, but external platforms may cache previews or apply different crops. Test a repository link in the destinations that matter to your project and inspect the result at a small display size. If text disappears, simplify the artwork or increase its scale within the 2:1 canvas. If a transparent logo vanishes into a dark or colored background, switch to a solid background or add a contrasting shape behind it.
When you replace an image, allow for the possibility that a previously shared link still displays an older cached preview for a while. The supplied GitHub guidance does not promise identical rendering or cache timing across third-party platforms, so judge the result on each destination rather than assuming one preview represents all of them.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
Settings or Social preview is missing
Open the repository itself and check the tab dropdown if Settings is not shown directly. You need repository-level access that allows settings changes. Organization policies or insufficient permissions can hide or restrict the area.
GitHub rejects the file
Confirm that the exported file is PNG, JPG, or GIF and that it is under 1 MB. Re-export after reducing dimensions or JPEG quality if necessary. Check the actual exported file size rather than the size of the editable source document.
The image looks blurry
Re-export at 1280 × 640 pixels when practical. Starting below GitHub’s recommended 640 × 320 minimum leaves less detail for downscaling and can make small type unreadable.
Transparent artwork looks wrong
Preview the PNG over light, dark, and colored backgrounds. GitHub supports transparency, but platforms differ in how they display it. Add a solid background when the artwork needs predictable contrast.
A popup or consent notice appears in an automated capture
In a manual workflow, dismiss the overlay before taking the screenshot. In ScreenshotNeo, enable the consent, popup, and chat-widget cleanup behavior; those steps can be turned off individually when you need the original page state.
The automated request returns a failure
Check the URL, API key, and network response. A page can fail because of a bot check, CAPTCHA, timeout, blank response, or load error. ScreenshotNeo identifies the page result and billing status in the X-Page-Verdict and X-Billed headers, and those failed categories are not billed.
Free tools Windows power users keep installed
One-click scans. No signup required.
FAQ
Can I use an animated GIF?
GitHub lists GIF alongside PNG and JPG as accepted formats. If the image contains important text, verify the first frame and the appearance on each platform where the repository link will be shared.
Should I upload a transparent PNG or a solid image?
Use transparency only after checking the artwork against the backgrounds your audience is likely to see. A solid background is the safer choice when those destinations are unknown.
Can a private repository’s preview be shared publicly?
GitHub allows an image to be uploaded to a private repository where an image was previously uploaded, but the preview can be shared from a public repository only.
Frequently Asked Questions
Does changing the social preview modify repository files?
No. The image is managed from the repository’s Settings → Social preview area rather than committed as a repository file.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11What should I do if the new image does not appear immediately on a social platform?
Check the repository’s Social preview setting first, then test the link again later; external platforms can cache previews and may not refresh on the same schedule.
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.
