Projects and portfolio

What to Include in a Python Project README

Give readers a reproducible Python run with the right interpreter, a sample input, an exact command, and expected output.

A Python project README should tell readers what the tool does, how to set it up, and how to recognize success. Give them one command to run with a sample input and show the expected output. Follow with the test command, common errors, and any license or data credits.

Open with the job the tool does

Start with the question your project answers. “Summarizes weekly totals from a reading log” gives the reader a purpose. Follow it with the result they can expect, such as a CSV with one line per week and a count of rejected inputs.

Name the project's boundary near the top. A tool might accept the format exported from one app. The first section is a good place to identify that format, especially if two similar exports produce different column names.

Show a complete run from a clean checkout

State the Python version or range you have exercised, the working directory, and any package installation step. Keep the example paths consistent with the repository. If you show the reader a filename in the sample command, make sure it exists in a fresh checkout. Confirm that the setup command installs into the environment used by the run command.

Include the output location and a short example of the expected result. If exact timestamps change, say which fields are variable and which invariants should hold. If the program writes a file, tell the reader whether repeating the command appends, replaces, or rejects the existing output.

Show a useful failure

Include one error a reader can recover from, with a clue that helps distinguish causes. “Missing input file” should point toward the expected location and current working directory. “Unexpected column names” should include the supported header pattern. Troubleshooting then becomes a check a reader can perform rather than a collection of guesses.

Give a test command if there are tests, and state what they exercise. The difference between “the test suite checks grouping and duplicate handling” and “tested on every operating system” matters. Link to any recorded environments or release checks if you have them.

Make the README easy to maintain

Keep commands together with the fixture they use. A new filename can break the instructions just as easily as it can break a test. When changing an interface, run the documentation example using a fresh working folder. A reader should never need a file left over from a previous run.

Move long background notes to a separate file when they interrupt the quick start. Leave a link next to the decision it explains. License terms, dependency sources, and credit for any data come last, where a downstream user can find them.

A good final review takes five minutes: open the published repository, use a clean environment, paste the sample command, and compare what happens with the README. Fix the first place you had to guess.

If it’s hard to tell where the sample should go, organize your examples and tests in the repository.

Sources and further reading

Related reading

Browse Projects and portfolio · Explore project tutorials

Search PythonProjects.org