I've found that when I clone a repo, the setup instructions in the README are often outdated - wrong runtime version, a package manager you don't have, an env var that hasn't been documented, a database that is supposed to be running, etc.

setupdoctor parses the necessary requirements directly out of the repo (via .nvmrc, engines, lockfiles, .tool-versions, .env.example, compose file and code) and compares them to the users system. Then it produces a checklist of mismatches and their solution. It can also attempt to auto-run all the solutions it can. The --install-hook flag runs setupdoctor after every git clone.

Currently it supports Node, Python, PHP, Ruby, Go, Rust, Java and .NET as well as monorepos. It will discover all the projects in a monorepo, label them and apply fixes to the correct repo.

The difficult component has been false positives. I initially interpreted "the code reads this env var" as "this env var is required." I ran it across 18 open source repos and approximately half of those had between 3 and 43 false positives, and all false positives were optional fields. Currently a false positive only occurs if the repo requires the field. This is either because the field is in .env.example or a config schema requires it (django-environ, Joi, zod, pydantic-settings, envalid, or denv). Or if the code would fail without it.

For Python and Node it will install all dependencies in addition to checking on the tooling and versions. For the other six languages it only does version and tooling checks and these languages have also been used less in practice. Version pins are strict so if a repo requires Node 24 it will fail if running on Node 26. It has been run on 78 actual repos, still not very many.

setupdoctor is a single Python file with no external dependencies. Install with pip install setupdoctor

If it makes an error on a repo that you are familiar with, I would love to know what repo.