GitHub Avatar: Square Crop That Survives the Circle
Crop a GitHub avatar that stays sharp in the circle: use a 500 x 500 square, keep the face centered, and export under 1 MB.
Contents
Your GitHub avatar should start as a clean 500 x 500 square, with the face or logo centered far enough from the edges that the circle mask does not bite into it. Keep the file under 1 MB, export as JPG or PNG, then check the tiny header version before you call it done.
Start with a square crop in Photos or Windows Photos
The fastest native fix is boring: crop the photo to a square before you open GitHub. Apple’s iPhone Photos guide includes a Square preset, and Microsoft Photos on Windows has preset aspect ratios too. Good enough for many headshots. Not enough for every logo.
I start there because native editors are already on the device, and they keep you from uploading a tall portrait and fighting GitHub’s crop box in a hurry. On iPhone Photos, open the image, tap Edit, tap Crop, unlock the aspect ratio if needed, then choose Square. On Windows, open the image in Photos, use Edit image, then Crop. It’s not fancy.
The drawback is preview. A square crop shows the canvas, not the circle GitHub will display in comments, pull requests, and the little top-right menu. A wide logo can look fine in the square and still lose its counter-form inside the circle. Seen it happen.
Use GitHub’s 500 x 500 recommendation as the export target
GitHub’s profile reference says profile pictures should be PNG, JPG, or GIF, under 1 MB, smaller than 3000 x 3000 pixels, and about 500 x 500 pixels for best quality rendering. That gives you a practical target: don’t upload the camera original.
The official upload flow also makes you crop during setup: Settings, Profile Picture, Edit, Upload a photo, crop, then set the new picture. I still prefer preparing the square first because the crop modal is the wrong place to make composition decisions. You want the face line, whitespace, and edge padding settled before GitHub touches the file.
For most avatars, 500 x 500 is enough because GitHub displays the same picture in several small contexts. Bigger source files mainly give GitHub more pixels to shrink. Close. The real catch is that a too-big file also raises the chance you’ll hit the 1 MB limit or soften detail during another resize.
If you’re also preparing work chat avatars, the same square-first rule carries over to RoundCut Slack note and RoundCut Zoom crop. Different platforms, same trap: the circle is what people see.
Keep the face or logo inside the circle preview
A safe GitHub avatar keeps the important part inside the middle 70 percent of the square. Put eyes slightly above center for a headshot, or keep a logo mark away from all four corners. The corners are dead space once the circle mask appears (which is where the crop gets unforgiving).
If your native crop looks close but you need to see the round result before upload, use RoundCut Circle Crop after the square crop. Drop the file in, center the crop, and export the result. No signup. The image stays in the browser.
That last part matters when the avatar is a client headshot, a private repo identity, or a company mark that isn’t public yet. But the tool can’t invent a better source photo. If the face is motion-blurred or the logo has a fuzzy edge, a circular mask just makes the problem easier to see.
Logos need more margin than faces. I usually leave at least one thick stroke of whitespace around the mark (more if the mark is thin), then check the crop at 64 x 64 by zooming the browser out or previewing the downloaded file in a small Finder or Explorer thumbnail. RoundCut Discord note has the same warning, only harsher because server icons often shrink even more.
Export under 1 MB without making the avatar mushy
The clean export order is crop first, resize second, compress last. If you compress the original 12-megapixel photo first, then crop it, you spend quality on pixels GitHub will throw away. Small job. Big difference.
For this article, I ran a local ImageMagick check with a simple 3024 x 4032 test portrait file. After a centered 500 x 500 crop, the JPG at quality 85 was 6,764 bytes, the PNG was 32,624 bytes, and the WebP was 2,128 bytes. The exact numbers aren’t the point; resizing first put every export far below GitHub’s 1 MB ceiling.
Use JPG for normal headshots. Use PNG for logos, flat illustration, or anything with crisp edges. If your PNG is still heavy because it has transparency or a lot of flat color detail, RoundCut PNG guide walks through the safer choices.
RoundCut’s image resizer is the direct fix when your crop is right but the pixel dimensions are not. If the file still lands too close to 1 MB, compress the avatar after resizing, not before.
One caveat: GitHub’s profile reference lists PNG, JPG, and GIF. WebP may be handy for other places, but I would not use it as the GitHub upload master. Export JPG or PNG for this one, then keep a WebP copy only if you’re reusing the avatar on a website.
Upload it to GitHub, then check the tiny versions
Upload the finished file in GitHub settings, use the crop step only for a tiny nudge, and set the new profile picture. Then check it in three places: your profile page, the top-right menu, and one old comment or pull request where the avatar appears small.
Don’t judge only the large profile page view. The small version is where bad crops show up: a forehead clipped by the circle, a logo corner missing, a dark mark disappearing in GitHub’s dark mode. If the avatar is for a developer portfolio, compare it with RoundCut LinkedIn guide too, because recruiters often see both on the same day.
The practical rule is simple: square at 500 x 500, center the subject, preview the circle, export JPG or PNG, stay under 1 MB. For a personal headshot, iPhone Photos or Windows Photos may be enough. For a logo, a tight crop, or a face near the edge, preview the circle before GitHub does it for you. That is the difference.
GitHub gives you the crop box. You bring the judgment. The avatar is small, but it follows every issue, commit, and comment you leave behind.
