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:
- -e stops at the first failing command, so you see the real error and not a pile of later failures.
- -u fails on unset variables, which catches "you need to export API_KEY first" steps the README never mentions.
- -x prints each command before it runs, so the log reads like a transcript.
- -o pipefail catches failures hidden inside piped commands such as `curl ... | sh`.
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:
- Python project that says "Python 3.10+": test on `python:3.10-slim` (the oldest version you claim) and on the newest one.
- Node project: use `node:<version>-slim` for each major version you support.
- "Works on any Linux" or installs system packages: use `ubuntu:24.04` or `debian:stable-slim`.
- Go or Rust binary install: use a plain `debian:stable-slim`, so you're testing the binary and not the toolchain.
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:
- `--add-file` needs git 2.31 or newer. On older git, commit `readme-steps.sh` on a throwaway branch.
- Commit your latest changes first. `git archive HEAD` ignores uncommitted edits.
- `--rm` deletes the container afterwards, so each run starts from zero.
- If your README tells users to install from a package registry (for example `pip install mytool` or `npm install -g mytool`), you can skip the archive step and run the script directly. Just make sure the version you're testing has been published.
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:
- [ ] A system package is needed but not listed (compiler, `git`, `libssl-dev`, `libffi-dev`, `ffmpeg`, `pkg-config`)
- [ ] The minimum language or runtime version isn't stated, or is wrong
- [ ] An environment variable or API key is used before the README mentions it
- [ ] The README references a `.env.example` or config file that isn't committed
- [ ] The package name in the install command doesn't match the published name
- [ ] The command name after install doesn't match what the quickstart uses
- [ ] The installed command isn't on PATH (common with `pip install --user` and global npm installs). The README should say how to fix it.
- [ ] A step depends on a file from an earlier step that the README skipped (e.g. `cd` into a folder that was never created)
- [ ] The quickstart starts a server, but the README doesn't give the port or the URL to open
- [ ] Code blocks include prompts (`$ `, `> `) or output lines mixed in with commands
- [ ] A `curl | sh` installer fails because `curl` isn't installed
- [ ] The steps only work on macOS (e.g. `brew`, `sed -i ''`), but the README doesn't say so
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:
- 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.
- 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.
- 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 .`.
- 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
- [ ] The script passes on the oldest and newest versions you support
- [ ] The script passes as a non-root user
- [ ] The README commands and the script are identical
- [ ] The README states what output to expect
- [ ] `install-log.txt` from the final run is saved
- [ ] `readme-steps.sh` is either deleted or kept in `scripts/`, so you can rerun it before every release
Rerun the test whenever you change dependencies or the install commands. It's quicker than answering "doesn't install for me" issues after launch.
Browse the Quillwork shop