How to Test README Install Steps in a Clean Docker Container

A step-by-step method to check that your README's install and quickstart commands work on a fresh machine before you launch. It includes a copy-paste test script, a checklist of common failures, and a fill-in "Tested on" template.

Your install steps work on your laptop, but your laptop is a poor test machine. It already has your global packages, cached dependencies, environment variables, the right language version, and files git doesn't track. A new visitor from Show HN or Product Hunt has none of that. If their first command fails, many will leave without filing an issue.

This guide shows how to run your README's install and quickstart commands in a fresh container, keep a log of what happened, and fix the gaps before launch. You need Docker installed and a git repo. Setup takes about 15 minutes.

Step 1: Copy your README commands into a script, exactly as written

Open your README and copy every command from the Install and Quickstart sections into a new file called `readme-steps.sh` at the root of your repo. Copy them exactly as written. Don't fix typos and don't add steps you "know" are needed. The point is to test the README, not your memory.

``` #!/usr/bin/env bash

readme-steps.sh: commands copied verbatim from README

set -euxo pipefail

--- Install (from README) ---

pip install .

--- Quickstart (from README) ---

mytool --version mytool init demo mytool run demo

echo "ALL README STEPS PASSED" ```

What the flags do:

If your README shows commands with a `$ ` prompt in front, delete the prompt in the script. Then fix the README too, because readers who copy the line will paste the `$` along with it.

Step 2: Pick a base image that matches what your README promises

Choose the image based on what your README says users need, not what you have installed:

Slim images are good for this because they leave out things like `git`, `curl`, `make` and C compilers. If your install needs any of these, the slim image will tell you, and your README should say so too.

Step 3: Send only committed files into the container

If you mount your working folder into the container, you'll bring along untracked files, build caches and your local `.env`. That hides exactly the problems you're looking for. Use `git archive` instead, so the container only gets what a fresh `git clone` would get, plus your test script:

``` git archive --format=tar --add-file=readme-steps.sh HEAD \ | docker run --rm -i python:3.12-slim \ bash -c 'mkdir -p /src && cd /src && tar -xf - && bash readme-steps.sh' \ 2>&1 | tee install-log.txt ```

Notes:

Step 4: Read the log from the bottom up

Open `install-log.txt`. If the last line is `ALL README STEPS PASSED`, the README works on that image. If not, the last `+` line shows the command that failed, and the lines below it show the error.

Fix the README, not just the script. Then copy the corrected commands into the script again and rerun until it passes. Keep the passing log. You can attach it to your launch PR or link to it in the README as proof that the steps were tested.

Step 5: Run the extra checks most people skip

Test as a non-root user. Docker runs as root by default, which hides permission problems. If your README never says `sudo`, add `--user 1000:1000 -e HOME=/tmp` to the `docker run` command and run again.

Test the other CPU architecture. On an Apple Silicon Mac, add `--platform linux/amd64` to test as an Intel/AMD Linux user would. If you're on x86, try `--platform linux/arm64`. This only works if Docker has emulation set up, which Docker Desktop does by default.

Test with no config. Don't pass any `-e` environment variables on the first run. If the tool needs a key or a config file, the README should say where to get it and show the exact line to set it.

Test the oldest supported version. If the README says "Node 18+", run the test on `node:18-slim`, not just your current version.

Checklist: the failures this test usually catches

Go through this list after each run:

Fill-in template: a "Tested on" install section

Once your test passes, put the evidence in the README. Readers trust install steps more when they can see what they were tested on.

```

Install

Requirements: [LANGUAGE] [MIN VERSION]+, [SYSTEM PACKAGES OR "nothing else"]

[INSTALL COMMAND]

Check it worked:

[COMMAND] --version

Tested in a clean [IMAGE NAME] container on [DATE] ([ARCH, e.g. amd64 and arm64]).

Quickstart

[FIRST COMMAND] [SECOND COMMAND]

You should see: [ONE LINE DESCRIBING EXPECTED OUTPUT] ```

The "You should see" line matters. It tells readers whether things worked without making them guess.

Worked example: a small Python CLI

Say the README says only `pip install .` and then `mytool init demo`. Here's how a first run on `python:3.12-slim` could go and what gets fixed after each failure:

  1. Run 1 fails at `pip install .` because a dependency needs a C compiler to build. Fix: add "Requirements: build-essential (Debian/Ubuntu)" to the README and `apt-get update && apt-get install -y build-essential` to the install steps. Better still, pin to a dependency version that ships prebuilt wheels.
  2. Run 2 fails at `mytool init demo` with an unset `MYTOOL_HOME` variable. Fix: give it a default value in the code, or add an `export` line to the quickstart.
  3. Run 3 passes as root. Run 4 adds `--user 1000:1000 -e HOME=/tmp` and fails on writing to `/usr/local`. Fix: change the README to install in a virtual environment (`python -m venv .venv && . .venv/bin/activate`) before `pip install .`.
  4. Run 5 passes as non-root on 3.10 and 3.12. Add the "Tested on" line and keep the log.

Each fix is a problem a real visitor would otherwise have hit in their first five minutes.

Before you post your launch

Rerun the test whenever you change dependencies or the install commands. It's quicker than answering "doesn't install for me" issues after launch.

More templates and kits
Browse the Quillwork shop