A GitHub profile README is content from a special repository — one named exactly the same as your GitHub username — that GitHub automatically displays at the top of your profile page, above your pinned repositories. It's the only place on GitHub where you get a fully custom, Markdown-rendered block of content tied to your identity rather than a specific project.
How GitHub decides to show it
GitHub checks for three conditions: the repository name must match your username exactly, the repository must be public, and it must contain a README.md file at the root. If all three are true, GitHub renders that file's content at the top of your profile automatically — no settings toggle required.
Setting one up
- Click "New repository" on GitHub.
- Name it exactly your username (GitHub will flag it as special automatically).
- Set visibility to Public.
- Check "Add a README file."
- Edit
README.mdwith your content and commit.
Refresh your profile page and the content appears immediately — there's no build step or deploy delay.
What actually goes in a good one
The strongest profile READMEs are short and specific rather than long and generic. A one-line identity statement, two or three project highlights with a measurable outcome each, a compact tech-stack list, and — optionally — one live widget like a GitHub stats card. Anything beyond that starts to compete for attention rather than add to it.
Common setup mistakes
- Naming the repo close to, but not exactly, your username — GitHub won't treat it as special.
- Leaving the repository private — it must be public to render.
- Putting the README in a subfolder instead of the repository root.
Frequently Asked Questions
Does the profile README repo need to be public?
Yes. If the repository is private, GitHub will not render it on your profile page.
Can I have both a profile README and normal repositories?
Yes, the username-named repository is separate from and doesn't affect your other repositories.
Will changes update instantly?
Yes — as soon as you commit changes to README.md, your profile page reflects them, usually within a few seconds.