It Works on My Machine: A Philosophy
Philosophers have long debated whether something can be said to exist if nobody observes it. Software engineers have a more practical version: does a feature work if it only works on one laptop?
"It works on my machine" is the most famous sentence in software development. It's said with confidence, defensiveness and a hint of desperation, usually to a colleague who is staring at an error on a different machine.
The philosophical position
On your machine, the code works. This is true. It is also, unfortunately, irrelevant, because your machine is not where customers live. Your laptop is a unique snowflake, shaped by years of installations, environment variables you forgot setting and that one library you installed globally in 2022 for a tutorial.
The real reasons
- Different versions of the language, libraries or tools.
- Missing environment variables or config files that exist only locally.
- Operating system differences: file paths (
\vs/), case-sensitive file names, line endings. - Local data: your database has test rows the server doesn't, or a cache hides a bug.
- Time zones and locales: dates and number formats behave differently.
- It doesn't actually work on your machine either, you just didn't test that path.
The cures
Pin your dependencies.
pip freeze > requirements.txt # or use a lock file: poetry.lock, uv.lock
npm ci # installs exactly what's in package-lock.jsonContainerise the environment so everyone, including the server, runs the same setup.
Use CI. If tests run on a clean machine for every pull request, "works on my machine" gets challenged automatically, before anyone deploys.
Document setup in a README, and test the instructions on a fresh machine occasionally. Better: a single command (make setup) that does everything.
Keep config in environment variables, with a .env.example file listing every variable the app needs.
Dev containers and reproducible environments let new teammates start coding in minutes instead of days.
The joke version of the cure
"Fine," said the manager. "Then we'll ship your machine." And that, more or less, is how containers were born. (It isn't really, but it's a better story.)
The deeper lesson
The phrase is really a statement about hidden assumptions. Every "works on my machine" bug is an assumption about the environment that nobody wrote down. Good engineering is largely the practice of making assumptions explicit: in lock files, configs, tests, documentation and automation.
So the next time you feel the four famous words forming, try five less famous ones instead: "Let me check what's different." It's less satisfying to say. It's much more likely to fix the bug before lunch.