A GitHub profile README is a Markdown file that GitHub shows at the very top of your profile page, above your pinned repositories. It's the closest thing GitHub has to an "about me" page, and it's often the first thing a recruiter or collaborator reads. This guide walks through setting one up from scratch, then covers the problems people most often hit.
How a profile README works
GitHub looks for a repository that meets three conditions:
- It has the same name as your username. If your username is
octocat, the repository isoctocat/octocat. - It is public.
- It has a
README.mdfile in its root folder, not in a subfolder.
When all three are true, the contents of that README appear on your profile automatically. There's nothing to switch on.
Step 1: Create the special repository
- Go to github.com/new.
- In Repository name, type your exact username. GitHub recognises it and shows a message saying you've found a special repository.
- Choose Public.
- Tick Add a README file, then click Create repository.
Visit your profile and you'll already see a starter README there.
Step 2: Write your README
Open README.md in the new repository and click the pencil icon to edit it. A simple, solid starting point looks like this:
# Hi, I'm Alex 👋
Full-stack developer building tools for small businesses.
- 🔭 Currently working on **a realtime collaboration app**
- 🌱 Learning **Rust**
- 📫 Reach me at **alex@example.com**
### Tech stack
TypeScript · React · Node.js · PostgreSQL · DockerClick Commit changes and refresh your profile. That's a working profile README. Everything else, like banners, badges and stats, is decoration on top of this.
Step 3: Make it look good, the quick way
Hand-writing badge URLs and HTML alignment takes a while. The MakeReadme generator does it for you:
- Enter your GitHub username. Your name, bio, location, social links, top languages and most-starred repos are filled in.
- Pick a style preset or browse the gallery, then adjust sections, colours and your tech stack.
- Check the live preview in GitHub's light and dark themes.
- Click Download to get
README.md.
Back in your repository, either edit README.md and paste the new content, or use Add file → Upload files to replace it with the downloaded file.
💡 Import your GitHub profile and get a styled README in about two minutes. Try it →
What to put in it
The best profile READMEs are short and scannable. Aim for:
- One line about what you do, e.g. "Backend engineer working on payments infrastructure". This matters more than anything else.
- What you're working on or learning, which gives people something to talk to you about.
- Your tech stack, as badges or a short list.
- Two to four featured projects with a sentence each.
- How to reach you: email, LinkedIn or a personal site.
For more inspiration, see 15 profile README ideas.
Troubleshooting
My README doesn't appear on my profile
- Check the repository name matches your username exactly.
- Make sure the repository is public. Private repositories never show on your profile.
- Confirm the file is named
README.mdand sits in the root of the default branch.
Images or stats cards are broken
Most profile decorations are images served by third-party services. If one is temporarily down or rate-limited, the image fails to load. See How to add GitHub stats for fixes, including self-hosting.
My changes don't show up straight away
GitHub serves external images through its own caching proxy, so an updated image can take a while to refresh. Text changes to the README itself appear as soon as you commit.
It looks wrong in dark mode
Images with dark text on a transparent background disappear on GitHub's dark theme. Use images with their own background, or serve separate light and dark versions. The Markdown cheat sheet shows how.
Next steps
- Add tech-stack badges and live stats.
- See how your profile scores with Roast my GitHub. It points out quick wins such as missing repo descriptions.
- Share your work with a GitHub profile card.
