deploy notes
Servers & scripts

A README template for a Python script someone else needs to run

Write a short handover that covers prerequisites, input, the exact run command, expected output, errors, and stopping—then rehearse it in a clean folder.

Beginner5 min read
In this guide

A useful README answers the questions someone asks before they can run your script: what they need, which file to use, what command to run, and how to recognize success.

You do not need a long project brochure. You need a short handover that works when the reader has only the files you actually provide. This guide gives you a template and a way to check it without relying on your usual working folder.

Gather the facts before copying the template

For your own script, note:

  • its supported Python version and operating system;
  • any packages and their existing installation instructions;
  • required input files and settings;
  • its exact command, expected output, and whether output is replaced;
  • how it reports a common error and how to stop it.

If you cannot answer one of these, inspect the script or ask its author before documenting a guess. Keep passwords, API keys, personal exports, and private addresses out of both the README and the sample files.

Save this as README.md

Place README.md beside the script. Markdown is ordinary text with simple heading and list markers; GitHub and many editors can display it as a formatted page. Use a plain-text editor and keep the .md extension.

Copy this template, then replace every REPLACE_... item with facts about your script. Remove sections only when they truly do not apply.

# REPLACE_SCRIPT_NAME

## What it does
REPLACE_ONE_TASK_AND_SCOPE

## Before you start
- REPLACE_SUPPORTED_OS_AND_PYTHON_VERSION
- REPLACE_VERSION_CHECK_COMMAND
- REPLACE_PACKAGE_INSTALLATION_OR_NO_PACKAGES_NEEDED

## Files and settings
- REPLACE_SCRIPT_FILENAME
- REPLACE_INPUT_FILENAME_AND_FORMAT
- REPLACE_REQUIRED_SETTINGS_AND_HOW_TO_SUPPLY_THEM
Keep private credentials outside this repository.

## Run
Open a terminal in this folder.
REPLACE_EXACT_COMMAND_IN_A_CODE_BLOCK

## Check the result
REPLACE_OUTPUT_FILENAME_OR_TERMINAL_MESSAGE
REPLACE_SMALL_CHECK_OF_ACTUAL_VALUES
REPLACE_WHETHER_EXISTING_OUTPUT_IS_REPLACED

## If it fails
- REPLACE_COMMON_ERROR_AND_CORRECTIVE_ACTION
- REPLACE_WHERE_TO_READ_THE_ERROR

## Stop
REPLACE_FINISHES_ONCE_OR_EXACT_BACKGROUND_STOP_COMMAND

For the exact command, insert a fenced code block: a line of three backticks, the command on the next line, then another line of three backticks. Do not leave a filename or password-shaped placeholder that looks ready to run.

If Windows and Linux need different commands, label them. If only one OS is supported, say so rather than advertising untested alternatives. “Install the dependencies” is not enough; include the actual requirements filename and command when packages are needed.

A small completed example

Here is a fictional handover for a script that counts nonblank lines in a UTF-8 notes file. It is an example of the level of detail, not a required replacement for your own project:

What it does: Counts nonblank lines in a small UTF-8 text file; it does not interpret the contents.
Before you start: Windows PowerShell, Python 3.12 or newer, checked with py --version. No extra packages. If Python is missing, use the official Python downloads and reopen the terminal.
Input: Save notes.txt beside count_lines.py as UTF-8 plain text. Put one note on each line. Blank lines are ignored.
Run: Open the folder in File Explorer, type powershell in its address bar, and run py count_lines.py notes.txt.
Check: For three notes separated by any blank lines, expect Nonblank lines: 3. Confirm the input yourself; the script prints a count and writes no output file.
Errors: A missing file prints Stopped: with a file error. An encoding error means the input is not readable as UTF-8; obtain a UTF-8 copy without discarding characters. Read the error in the terminal.
Stop: It finishes after the count. Ctrl+C interrupts a run if needed; no task remains scheduled or running in the background.

If you want to rehearse that completed example, save this as count_lines.py in a separate practice folder:

import argparse

parser = argparse.ArgumentParser(description="Count nonblank UTF-8 text lines.")
parser.add_argument("file")
args = parser.parse_args()

try:
    with open(args.file, encoding="utf-8-sig") as source:
        count = sum(1 for line in source if line.strip())
    print(f"Nonblank lines: {count}")
except (OSError, UnicodeError) as error:
    parser.exit(1, f"Stopped: {error}\n")

Save a notes.txt with three short fictional notes, follow the handover, and confirm the count. The important lesson is that the README supplies both the input and the success check; a runnable command alone is not a complete handover.

Rehearse your own README in a clean folder

Copy only the files you plan to hand over into a new practice folder. Do not use real customer data. Open a new terminal so you do not unknowingly rely on an already activated environment or an old setting.

Follow the README from top to bottom:

  1. Check the documented version and set up the documented environment.
  2. Create or supply the stated sample input.
  3. Run the exact command as written, without borrowing missing files from your normal folder.
  4. Compare the actual result with the stated check.
  5. Try the main safe failure, such as a missing input file, and follow the documented recovery.
  6. Follow the stop instructions if this script stays active.

Whenever you have to improvise an obligatory step, put it into the README and repeat that affected step. For a recurring or continuous script, document its actual scheduler or service stop command; Ctrl+C in a different terminal will not stop an independently running service.

Do not include test credentials to make the rehearsal easier. Explain where the recipient should supply their own credentials securely. For a dependency-based Python project, keep requirements with the source and document its environment instead of handing over a copied .venv folder.

Your result is a handover another person can follow, with a check that distinguishes “the program finished” from “it produced what we wanted.” Keep it current when the input, command, Python version, or output behavior changes.

← Back to servers & scripts guides