How to Pin Python Dependencies with pip freeze

Here's the article:

Stop Breaking Your Code: Pin Dependencies with pip freeze

Ever had that sinking feeling when you come back to a Python project you haven't touched in months, hit "run", and get a cascade of import errors? You're not alone. It's the classic "it works on my machine" problem, and the culprit is almost always un-pinned dependencies.

Let's be real — Python's flexibility with packages is both its superpower and its Achilles' heel. One tiny update to a library you barely think about can silently break your entire application. That's where pip freeze comes in, and it's simpler than you might think.

What exactly is pip freeze?

Think of pip freeze as a photograph of your current Python environment. It captures every single package you've installed, along with its exact version number. Run it in your terminal, and you'll see something like this:

requests==2.31.0
flask==3.0.0
numpy==1.26.2

Each == means "exactly this version — no guessing, no surprises."

The problem with loose dependencies

Here's what happens at PythonSkillset when someone installs packages without pinning: Six months later, requests releases version 3.0.0 with breaking changes. Your code that worked perfectly now throws errors because it expected the old behavior. Team members who clone your repo get different versions, and suddenly everyone's debugging different issues.

It's a mess, and it's entirely avoidable.

How to actually use pip freeze

First, create a clean virtual environment. No shortcuts here:

python -m venv myproject_env
source myproject_env/bin/activate  # On Windows: myproject_env\Scripts\activate

Install what you need:

pip install requests flask numpy

Now take the photo:

pip freeze > requirements.txt

That requirements.txt file is now your project's dependency contract. Anyone else (or you, six months from now) can recreate the exact same environment:

pip install -r requirements.txt

When things get messy

Real projects often have dependencies with their own dependencies. pip freeze catches all of them — even the ones you didn't explicitly install. That's usually fine, but it can create conflicts down the road.

Here's a better approach for production projects: be explicit about your top-level dependencies in a separate file (like requirements.in), and use pip-tools to compile your requirements.txt from that. But that's an advanced topic — for most teams, a simple pip freeze is already miles ahead of nothing.

The one thing most people get wrong

Don't commit requirements.txt to your repo without reviewing it first. I've seen projects with --editable installs, platform-specific packages, or even internal tools listed. Clean it up. Remove what's not needed. Add comments for anything unusual.

Your future self (and your team) will thank you.

A final thought

Pinning dependencies isn't about being paranoid — it's about being professional. At PythonSkillset, we've seen too many projects derailed by a single unexpected package update. pip freeze costs you 10 seconds now and saves you hours of debugging later.

Next time you start a Python project, take that photo. Your code will thank you.