Your GitHub Profile Picture: What It's Actually Doing for You

A GitHub profile picture is a square PNG, JPG or GIF under 1 MB and smaller than 3000 × 3000 pixels, with roughly 500 × 500 recommended. GitHub crops it to a circle for personal accounts and renders it mostly between 16 and 64 pixels wide. At that size recognition beats polish — and an illustrated avatar is genuinely acceptable here.

That last part is what makes this a different question from every other profile photo article. On a corporate profile, a cartoon of yourself reads as a refusal to participate. On GitHub, it reads as normal. The interesting question is not whether you're allowed an avatar — you are — but what your current picture is doing for you when a maintainer, a recruiter or a conference reviewer lands on your profile and spends four seconds there.

Where GitHub actually shows your avatar

Your avatar is not one image at one size. GitHub reuses a single upload across a dozen surfaces, and almost every one of them is tiny. GitHub's own Primer design system documents an avatar scale that starts at 16px and increments by four up to 32px, then by eight up to 48px, with 64px the largest size on the scale. The big version on your profile page is the exception, not the rule.

• Commit history rows — a small avatar next to every commit message in a repository's log
• Contributor lists on a repo's landing page and insights tab
• Issue and pull request threads — beside the opening post and every single comment you leave
• Review requests and approvals on a PR, often at the smallest size on the scale
• Notification rows, mentions and reaction pile-ups
• Organization member grids and team pages
• Your profile page — the one place it renders large enough for detail to matter

So the honest way to evaluate a candidate image is not "does this look good?" but "does this look like a specific, identifiable entity at the size of a favicon, repeated forty times down a scrolling issue thread?" Most photographs fail that test not because they're bad photographs but because they were cropped for a different job — a job where the viewer had four hundred pixels to work with instead of twenty-four.

Circle or rounded square?

Primer draws the distinction by what the account represents: circular avatars represent individual people, and square avatars represent non-human entities such as bots, AI agents, teams and organizations. Your personal account renders as a circle. An org account renders as a rounded square. You upload a square file either way and let GitHub do the masking — which means anything living in the corners of your image gets cut off on a personal account.

GitHub profile picture size and upload specs

The numbers themselves are undemanding, which is why almost nobody gets them wrong — the failures on GitHub are compositional, not technical. Still, it's worth knowing the ceiling and the recommendation, because they tell you how much resolution is actually being used and how little you need to worry about file weight.

• Formats: PNG, JPG or GIF
• File size: less than 1 MB
• Maximum dimensions: smaller than 3000 × 3000 pixels
• Recommended: about 500 × 500 pixels for the best rendering quality
• Default: a randomly generated identicon, derived from a hash of your user ID
• Gravatar: if the email on your account has a Gravatar attached, that image shows by default instead of the identicon
• To change it: Settings → Profile, then the pencil Edit control under "Profile Picture" → Upload a photo…, crop, and Set new profile picture

Two practical notes. First, 1 MB is generous for a 500-pixel square, so there is no reason to ship a compressed, artifact-ridden file — export at quality and you'll still land well under a couple of hundred kilobytes. Second, GIF is accepted, but an animated avatar in a code review thread is a distraction tax you're charging your colleagues forty times a page.

The identicon: what the default costs you

The identicon is the coloured 5 × 5 sprite GitHub assigns every new account. GitHub's own account of the design describes walking through a hash of the user ID and switching pixels on or off depending on whether values come out even or odd, with the colour derived from the same hash. You can't reroll it, and it carries no information about you beyond "this account exists."

Going back to it later is easy enough — Settings → Profile → Edit → Remove photo restores the identicon, unless the email on your account has a Gravatar attached, in which case the same control reads Revert to Gravatar and the identicon is no longer available to you. But an identicon is not a neutral choice, though it feels like one. It gets read in one of two ways, and you don't get to pick which:

1. 1"This person never finished setting up." The most common reading, and the one that hurts. It groups you with abandoned accounts, throwaway forks and drive-by contributors. In an issue thread where four other people have faces, the identicon reads as the least invested party.
2. 2"This person deliberately keeps a low profile." A real and respected posture in open source, but it only reads that way when the rest of the profile is strong — a filled-out README, meaningful contribution history, a consistent handle. Emptiness plus emptiness reads as abandonment.

Where the identicon is genuinely fine: bot accounts, service accounts, forks you maintain for internal reasons, and established maintainers whose handle is already the recognizable thing. Where it costs you real money: an active job search, a project you want people to trust enough to install, a conference CFP, developer relations work, or any consulting where the buyer is a human deciding whether you look like someone they'd put on a call with their CTO.

Real face, illustrated avatar, or logo: what each one buys

This is the actual decision, and it deserves more than a blanket "always use a real photo." Each option trades a different thing away. What you're really choosing is how much recognition transfers off GitHub — to a LinkedIn tab open next to it, to a conference lanyard, to a video call where someone has to match a name to a face.

A real photograph

Highest transfer value, lowest optionality. The same face works on GitHub, on LinkedIn, on a speaker page, on a Slack workspace and on a video call — which is the entire point of a consistent image. It's the only option that lets a recruiter confirm, in one glance, that the GitHub account and the LinkedIn profile are the same human. The cost is real: you're permanently tying a public handle to your face, and once your contribution history is indexed alongside it, that's not something you quietly undo.

An illustrated avatar or character

Culturally native to GitHub in a way it simply isn't on a corporate profile. A bold, high-contrast illustration can actually out-perform a photograph at 20 pixels — flat shapes and hard edges survive downscaling better than the soft tonal gradients a face is made of. It preserves pseudonymity, which for some contributors is a safety requirement rather than a preference. The cost is that it transfers nowhere: it can't go on a résumé, it doesn't help anyone recognize you at a meetup, and in more conservative hiring processes it can read as an unwillingness to be identified.

A logo or wordmark

Correct for organization accounts, weak for individuals. On a personal account a logo tends to read as a bot or a marketing account, which is precisely the wrong signal in a code review. If you run a one-person consultancy and want the brand visible, put it in the profile README and the bio — not in the circle.

A quick way to decide, in order:

1. 1Do you need this account to be findable as you, by name, by people hiring? Use a real photograph. Nothing else does this job.
2. 2Do you maintain something people install and run? Use a face or one consistent, distinctive avatar you use absolutely everywhere. Trust in supply-chain-adjacent contexts is partly a recognition problem.
3. 3Do you contribute under a handle you intend to keep separate from your legal identity? Use an illustrated avatar, and use the identical file on every platform.
4. 4Is this an organization or bot account? Use the logo, and expect a rounded square.

What actually survives at 20 pixels

If you've decided on a photograph, the craft question is narrow and specific: what information survives being scaled to the width of a checkbox? The answer is head shape, hair silhouette, value contrast and one dominant colour. Everything else — expression nuance, tie pattern, background detail, skin texture — is gone before the browser finishes rendering.

• Crop tighter than feels comfortable. Head plus a sliver of shoulder. A half-body shot that looks fine at 400px becomes an unidentifiable smudge at 24px.
• Put a value gap between your head edge and the background. Dark hair on a dark background merges into one blob at small sizes. This is the single most common failure.
• Kill busy backgrounds. Bookshelves, foliage and office scenes turn to visual noise. Our guide to choosing a headshot background covers the purpose-by-purpose logic; if you want the specific mechanics of surviving a small circular crop, the piece on backgrounds in a circular crop is the one to read alongside it.
• Eyes at roughly the upper third of the frame. Centering your whole head leaves dead space above it and pushes your face smaller.
• No text, logos or lanyards. Unreadable at every size GitHub uses, and they date the photo.
• Test it properly. Drop the file into a document, scale it to about 20 pixels, and look at it from arm's length. If you can't tell it's you, neither can anyone else.

One more thing worth knowing about small circular renders: they punish asymmetry in the crop far more than large ones do. A face sitting slightly left of centre reads as deliberate composition at profile-page size and as a mistake at 24 pixels, because the circular mask amputates one cheek and leaves a crescent of background on the other side. Centre the head horizontally, and let the vertical positioning do the interesting work.

The commit email trap nobody warns you about

Here's a failure mode specific to GitHub that has nothing to do with the image you uploaded. You can have a perfect avatar and still see a generic grey placeholder sitting next to half your commits — because GitHub does not attach avatars to commits by username. It matches the email address written into the commit header against the addresses registered on GitHub accounts.

If that address isn't on your account, GitHub marks the commit with an unrecognized author and shows the default placeholder — or, if that email happens to have a Gravatar attached, someone else's idea of your face entirely. Generic local addresses like jane@computer.local are a harder case: GitHub's documentation states plainly that they cannot be added to accounts and linked to commits at all, so anything authored with one never links and never appears in your contribution graph.

1. 1Check what git is actually using: git config user.email, both globally and inside the repo in question.
2. 2If it's a real address you own, add it to your GitHub email settings. This is retroactive: GitHub rebuilds your contributions graph automatically when you add the address, though it can take up to 24 hours to show up.
3. 3If it's a generic local address that can't be added, only rewriting history changes anything — those commits stay unlinked permanently. Fix the config so it stops happening going forward.
4. 4Consider switching git to the noreply address GitHub provides, which links commits to your account without exposing a real inbox. For accounts created since July 2017 it takes the form ID+username@users.noreply.github.com; older accounts may have the shorter username@users.noreply.github.com form. The ID-based version keeps working if you later change your username.

For anyone using GitHub as a portfolio during a job search, this is worth ten minutes. A contribution graph with holes in it, or a commit log where your face appears intermittently, quietly undercuts the exact thing you're pointing people at — and the fix is a one-line config change plus a checkbox in settings.

The twitter profile picture size, and every other surface you own

Most developers who care about a GitHub avatar also have an X account, a personal site and a conference bio somewhere. The recognition value of a profile photo compounds only when it's the same photo in all of them, so it's worth exporting once, properly, rather than uploading a different crop to each service over three years.

• X (Twitter): the recommended twitter profile picture size is 400 × 400 pixels, with a 2 MB maximum, in JPG, PNG or GIF. X crops it to a circle at a range of display sizes, so the same centre-weighted crop logic applies.
• GitHub: about 500 × 500 recommended, under 1 MB, PNG/JPG/GIF, circular for personal accounts.
• LinkedIn: different numbers again, and they change more often than the others — our LinkedIn photo sizes and specs reference is the page that owns those, including the banner dimensions.
• Work chat: Slack and Teams have their own quirks and their own social norms, covered in our piece on the work profile picture people actually see all day.

The workflow that saves you repeating this: keep one square master file at 1000 × 1000 pixels, exported from the original at full quality. Everything else is a downscale from that master. When a platform changes its recommendation — and they do — you re-export in thirty seconds instead of hunting for whatever original you used in 2024.

The developer job search: one photo that has to work in both places

This is the situation where the GitHub-tolerates-avatars norm collides with reality. During an active search, a recruiter or hiring manager will have your LinkedIn and your GitHub open in adjacent tabs. LinkedIn expects a face. GitHub doesn't. If those two tabs show a photograph and a cartoon axolotl, the person has to do identity reconciliation work before they can evaluate you.

Three workable approaches, in descending order of how much friction they remove:

1. 1Same photograph on both, permanently. Cleanest signal, zero reconciliation cost, and it also covers the conference bio and the Slack workspace on day one of a new job. This is what most people should do.
2. 2Face on GitHub for the duration of the search, then revert. A reasonable compromise if you value pseudonymity in normal times. Set a calendar reminder, because the version you forget to change is the one that stays up for four years.
3. 3Keep the avatar, but make everything else match perfectly. Identical display name, identical handle where possible, a link to your GitHub in your LinkedIn profile and vice versa, and a profile README that names you. This works — it just asks the reader to do more, which in a fifty-candidate pipeline is not a favour you want to be asking.

What the photo itself should say varies more by seniority than most people expect. A new grad and a staff engineer are solving different problems with the same square — one is establishing that they're a serious professional, the other is establishing approachability at a level where people assume competence already. Our breakdown by career stage works through what each of those needs from the image.

Actually getting the photo

Three routes, and for a 500-pixel square the gap between them is narrower than for a printed press portrait. Be honest with yourself about which constraint is actually binding — for most developers it's time and a dislike of being photographed, not budget.

Your phone and a window

Genuinely sufficient for this use case. A north-facing window, a plain wall a couple of feet behind you, the rear camera on a timer, and about twenty frames. At the sizes GitHub renders, the difference between window light and a studio strobe is largely invisible. The full DIY method is here, including the distance and lens details that stop your nose looking enlarged.

A photographer

Still the best option when you need range — a headshot plus environmental shots plus something for a speaker page — or when you want a second pair of eyes directing your expression, which is the part almost nobody can do alone. For a single circular avatar it's more capability than the surface requires, but the files last years and they hold up at sizes GitHub will never ask for.

AI generation

Fast and cheap, with two honest caveats worth stating plainly by a company that sells it. First, likeness drift: AI-generated portraits sometimes subtly alter facial structure, and the smaller the render, the less that matters — which makes GitHub a more forgiving surface for AI output than a printed conference programme. Second, norms: using a generated portrait is broadly accepted for professional profiles now, but the expectation is that it looks like you. We've written both an honest comparison against hiring a photographer and a piece on when disclosure actually matters — the first is for deciding, the second for the etiquette question once you've decided. If you want to see the output before committing, our AI headshot generator is free to try.

A fifteen-minute checklist

Everything above collapses into one short sitting. Do it in a single pass rather than across a month, because the value is in consistency and consistency is exactly what gets lost when you upload one file today and get to the others eventually. Block out a quarter of an hour and work down the list.

1. 1Decide the category first — face, avatar, or logo — based on whether you need recognition to transfer off GitHub.
2. 2Export one square master at 1000 × 1000, then a 500 × 500 copy under 1 MB for GitHub and a 400 × 400 copy under 2 MB for X.
3. 3Crop to head plus a sliver of shoulder, eyes at the upper third, with visible contrast between your head edge and the background.
4. 4Shrink the file to about 20 pixels and check it's still identifiable from arm's length.
5. 5Upload to GitHub, and confirm it renders as expected in a real issue thread, not just on your profile page.
6. 6Run git config user.email and make sure that address is registered on your GitHub account, or switch to the noreply address.
7. 7Push the same image to X, your personal site and your conference bio in the same sitting — the value is in the consistency, and it evaporates if you do it piecemeal over a year.

None of this makes anyone merge your pull request. But your avatar appears next to every argument you make in a review, every issue you open and every commit you land, at a frequency no other photograph in your professional life comes close to. For an image that gets that many impressions, fifteen minutes is a rounding error.