How do I add a README to my GitHub profile?

Create a new public repository named exactly like your GitHub username, tick "Add a README file", then paste the generated Markdown into README.md and commit. It appears at the top of your profile straight away.

Is the README generator free?

Yes. There is no sign-up and no limit, and everything runs in your browser. Nothing you type is stored.

Can I edit the README afterwards?

Yes. It is plain Markdown, so you can change anything in GitHub's editor or any text editor.

Why does the preview look slightly different on GitHub?

The preview follows standard GitHub Markdown, but GitHub applies its own styles and themes. Headings, lists, links, tables, code and images all carry over.

Free tool

GitHub README Generator

Fill in a few fields and get a clean README for your GitHub profile or your project, with skill icons, stats cards and setup steps. Copy it or download README.md. Free, no sign-up.

Your name

GitHub username

Needed for the stats cards.

Headline

About you

Currently working on

Learning

Ask me about

Location

Tech stack

GitHub cards

Stats cardTop languagesProfile views counter

X / Twitter

Website

Add a small “made with” link at the end

# Hi, I'm Your Name 👋

## Tech stack

![TypeScript, React, Node.js, PostgreSQL, Docker, Git](https://skillicons.dev/icons?i=ts,react,nodejs,postgres,docker,git&theme=dark&perline=12)

_Made with the free [GitHub README generator](https://www.chaudharyusama.com/tools/readme-generator)._

To show it on your profile: create a public repository named exactly like your username, add a README.md, and paste this in.

Profile README or project README?

A profile README appears at the top of your GitHub profile once you create a public repository with the same name as your username and add a README.md to it. A project README is the front page of a repository: what the project does, how to install and run it, and how to contribute. This generator writes both.

What makes a good README

Say what it is in the first line. Show it, with a screenshot or a demo link. Then answer the next three questions every visitor has: how do I run it, how do I use it, and who do I ask. Badges and stats are decoration; the setup steps are what people come for.

About the images in your README

Skill icons come from skillicons.dev and stats cards from the community github-readme-stats service, and GitHub loads them each time your page is viewed. Both are popular and free. If a card ever fails to load, the rest of your README still works, and for an important profile you can host the stats service yourself.

Frequently asked

How do I add a README to my GitHub profile?: Create a new public repository named exactly like your GitHub username, tick "Add a README file", then paste the generated Markdown into README.md and commit. It appears at the top of your profile straight away.
Is the README generator free?: Yes. There is no sign-up and no limit, and everything runs in your browser. Nothing you type is stored.
Can I edit the README afterwards?: Yes. It is plain Markdown, so you can change anything in GitHub's editor or any text editor.
Why does the preview look slightly different on GitHub?: The preview follows standard GitHub Markdown, but GitHub applies its own styles and themes. Headings, lists, links, tables, code and images all carry over.

Need the project behind the README?

I build web and mobile products from idea to launch, with clean code and documentation you can hand to the next developer.

Idea to launch Book a free call