Python’s requirements.txt vs Node’s package.json

A shared, human-friendly mental model we build while moving between ecosystems

In modern software development, the specific language or ecosystem we use matters far less than it once did. It is now routine to combine a Python backend, a Node.js microservice, a Flutter frontend, a Go CLI, or even a Rust utility within the same system.

Frameworks evolve, syntaxes change, and tooling shifts every year. What does not change is the need to understand how an ecosystem thinks. Once we grasp the mental model behind a toolchain, everything else becomes easier—whether we are building Docker images, deploying to Cloud Run, wiring MCP agents, or simply trying to run an application without mysterious dependency errors.

One of the most common sources of confusion for developers switching between Python and Node is dependency management. Both ecosystems solve the same problem, but they approach it very differently. Without a plain‑language explanation, it can feel like stepping into a parallel universe.

Let’s break it down.

---

1. Both ecosystems need a dependency list — they just manage it differently

Think of dependencies as a shopping list for our project.

• Python uses a manually maintained list.

• Node.js uses an automatically managed list.

That single distinction explains most of the confusion we run into.

---

2. Python: we maintain the list ourselves

In Python, installing a package does not automatically update our dependency list.

pip install flask

After this command:

• Flask is installed in our environment.

• requirements.txt remains unchanged.

If we want our project to remember this dependency, we must explicitly update the file:

pip freeze > requirements.txt

This is analogous to writing our grocery list by hand. We decide what goes on it and when it gets updated.

Note: Modern Python workflows often use tools like pip-tools, Poetry, or PDM to automate this process, but plain pip does not do this by default.

---

3. Node.js: the list updates itself for us

In Node, installing a package does update the dependency metadata automatically.

npm install express

npm performs three actions:

• Updates package.json (declares the dependency range)

• Updates package-lock.json (records the exact resolved versions)

• Installs the package into node_modules/

This is like having a smart shopping list that records everything we buy without asking.

We do not manually maintain the dependency list—npm does it for us.

---

4. The key distinction: npm install vs npm install <package>

This is one of those details that usually trips us up when we move between ecosystems.

npm install express

• Installs the package

• Updates package.json

• Updates package-lock.json

npm install

• Installs only what is already listed in package.json

• Does not modify any files

This is the Node.js equivalent of:

pip install -r requirements.txt

---

5. Docker: same concept, different files

Python developers are familiar with this Docker pattern:

COPY requirements.txt .
RUN pip install -r requirements.txt

Node.js follows the same principle:

COPY package.json package-lock.json ./
RUN npm install

The critical rule

• ❌ Do not copy node_modules/ into the image

• ✅ Let Docker build its own node_modules/ inside the container

This ensures builds are:

• Clean

• Reproducible

• Platform‑independent

And it avoids the classic “works on my machine” failure mode.

---

6. Why Node has both package.json and package-lock.json

In simple terms:

• package.json describes what we want (dependency names and version ranges)

• package-lock.json records what we actually got (exact versions and dependency tree)

This guarantees that everyone—developers, CI, and production—installs the same dependency graph.

Python does not provide this behavior out of the box. To achieve similar guarantees, we must use additional tooling such as pip-tools or Poetry lock files.

---

7. Common mistakes we tend to make (and how we avoid them together)

Mistake 1: Editing package.json manually ✅ Let npm manage it.

Mistake 2: Committing node_modules/ to Git ✅ Never do this. It bloats repositories and breaks portability.

Mistake 3: Copying node_modules/ into Docker images ✅ Always install dependencies inside the container.

Mistake 4: Running npm install and expecting new dependencies to appear ✅ Only npm install <package> modifies dependency files.

---

8. The simplest way to remember the difference

If we remember only one sentence, let it be this:

Python makes us maintain the list. Node maintains the list for us.

Everything else flows from that mental model.

---

Final thoughts (from learners, not lecturers)

We’re all switching stacks more than ever now. Most of us learned Python, Node, Docker, or dependency management not in isolation — but in pieces, often out of necessity.

This comparison isn’t about mastering tools. It’s about recognizing patterns early, so we spend less time fighting our toolchains and more time building things that matter.