README

basicwidespread

A README is an introductory file for a software project: it briefly describes what the program is, what it is good for, and how to install and use it.

In plain terms

A README is like a short guide placed on top of a box: before touching anything, you learn from it what you are holding and how to get started. Its name also asks for this: 'read me'.

Most software projects, especially open-source ones, have it in their main directory, nowadays mostly named README.md. It typically contains: what the program does, how to install and run it, what the most important commands are, and who to contact if you get stuck.

Detailed documentation is the manual; the README is just the entry point. Its purpose is to let you decide within minutes whether you need the project and how to get started.

Today, AI agents read them too. A coding agent often consults the README to learn how the project is built and how to run it.

How it works

The project creator creates a simple text file named README in the project's root directory, most commonly in Markdown format (README.md) today.
It outlines the essence: the project's goal, installation steps, one or two usage examples, the license, and how to report bugs or contribute.
Code-sharing platforms such as GitHub or GitLab automatically display it on the project's front page, formatted with headings, lists and images.
The interested party reads this first, then installs and tries out the program by following the commands in it.
As the project changes, the README must also be updated; otherwise, the guide and reality diverge.

An everyday example

An article recommends a free program, and the link leads to GitHub. The formatted description appearing below the file list, with installation steps and screenshots, is the README itself. This reveals whether the program runs on your machine and what you need to type to start it.

Who is affected

developerThis person writes and reads it the most: a good README saves hours for everyone who joins the project later. → Code

jobseeker, new graduateThe README of your own projects is your calling card: a potential employer first sees from this what you have built and how well you can explain it clearly. → Work & HR

parent, student, teacherAnyone learning or teaching programming starts from the README in almost every downloaded example project. → Education & Family

entrepreneur, executiveIf your company orders or takes over software, the existence and quality of the README is a quick signal of how organized the work is.

A common misconception

MythThe README is just a formality written by programmers for programmers, and can be safely skipped.

In realityIt is precisely aimed at the outsider, the person who knows nothing about the project yet. Many installation issues could be avoided if someone read it first.

Limits and risks

The README becomes outdated quickly: if the code changes but the description does not, the commands inside no longer work.
There is no mandatory standard, so quality varies greatly: one project may have a thorough guide, another just a single line.
Do not run commands listed in a README blindly from unknown sources, as the text guarantees nothing about the program's security.
If an AI agent works on the project, it may interpret the README text as instructions, so a maliciously written file could mislead it.

Similar, but not the same

Documentation – Documentation is the complete, detailed manual; the README is only the short entry point, which often links further.
AGENTS.md – AGENTS.md is a work instruction specifically for coding agents, while README is an introduction written primarily for humans.
Changelog – The changelog lists what changed from version to version, while the README explains what the project is and how to use it now.

Related concepts

Broader

Documentation, Software development

Narrower

README.md, Profil-README

On the edge

Markdown, Repo, GitHub, AGENTS.md, Open source

A brief history

The practice dates back at least to the 1970s, when programs included a text file named README. Due to its all-caps name, the file appeared at the top of file lists on many systems, making it easy to spot. GitHub, launched in 2008, greatly aided its spread by automatically displaying the file on project homepages.

Where things stand

As of late 2026, it is a basic element of virtually every serious software project. READMEs are increasingly written with AI, and coding agents regularly use them to get their bearings, while instruction files written specifically for agents have also appeared alongside them.

Status: 2026 November

Also known as

README · README.md · readme · ReadMe · README.txt · readme file · read me

Sources

Wikipedia: README

This entry was machine-edited and has undergone machine expert review; the “In the news” section updates automatically from Agent Age stories.