Skip to main content

Managing Packages with Pip: Using requirements.txt

In the last article, we learned the basics of pip for installing and removing individual packages. While that's useful, real-world projects almost always depend on multiple external packages. Managing these dependencies is a critical skill for collaboration and for ensuring your project runs reliably on different machines.

The standard, professional way to manage project dependencies in Python is with a requirements.txt file.

📚 Prerequisites​

You should know how to use basic pip commands:

  • pip install <package_name>
  • pip list

🎯 Article Outline: What You'll Master​

In this article, you will learn:

  • ✅ What a Dependency Is: Understand that dependencies are other packages your project needs to function.
  • ✅ The requirements.txt File: Learn what this file is and why it's the standard for managing dependencies.
  • ✅ pip freeze: How to automatically generate a list of your project's dependencies.
  • ✅ pip install -r: The command to install all dependencies from a requirements.txt file in one go.
  • ✅ The Reproducibility Workflow: Understand the standard workflow for managing dependencies in a project.

🧠 Section 1: What Are Dependencies?​

A dependency is an external, third-party package that your project relies on to work.

For example, if you are building a web application with the Flask framework, your project depends on Flask. If you use the requests library to fetch data from an API, your project depends on requests.

As your project grows, you might use 5, 10, or even 50+ external packages. It's impossible to keep track of them manually. You need a system to document them, and that system is the requirements.txt file.

💻 Section 2: The requirements.txt Workflow​

This file is a simple text file that lists all the packages your project needs, along with their exact versions. This acts as a blueprint for recreating your project's environment.

Let's walk through the standard workflow.

Step 1: Install Your Packages​

As you develop your project, you'll install packages as you need them. Let's imagine we're building a simple data analysis script that needs pandas for data manipulation and matplotlib for plotting.

pip install pandas
pip install matplotlib

Step 2: Generate the requirements.txt File with pip freeze​

Once you have your packages installed and your code is working, you need to record them. The pip freeze command is perfect for this. It outputs a list of all the third-party packages installed in your current environment and, crucially, their exact versions.

pip freeze

Example Output:

cycler==0.12.1
fonttools==4.43.1
kiwisolver==1.4.5
matplotlib==3.8.1
numpy==1.26.1
pandas==2.1.2
pillow==10.1.0
pyparsing==3.1.1
python-dateutil==2.8.2
pytz==2023.3.post1
six==1.16.0
tzdata==2023.3

Notice that pandas and matplotlib have their own dependencies (like numpy and pytz), which pip freeze includes automatically. This is vital for ensuring the environment is perfectly replicated.

To get this output into a file, we use a command-line redirect (>):

pip freeze > requirements.txt

This creates a requirements.txt file in your current directory. You should always commit this file to your version control system (like Git). It's just as important as your Python source code.

Step 3: Install Dependencies from requirements.txt​

Now, the magic happens. When a new developer (or you, on a new computer) clones your project, they don't have to guess what to install. They can set up the entire environment with a single command.

The -r flag tells pip to install from a file.

pip install -r requirements.txt

Pip will read every line in requirements.txt and install the exact version of every package specified. This guarantees that everyone working on the project has an identical set of dependencies, which dramatically reduces "it works on my machine" problems.

🛠️ Section 3: Why Pinning Versions is Important​

The == in the requirements.txt file is called "pinning". pandas==2.1.2 means "install exactly version 2.1.2 of pandas".

Why is this so important?

  • Stability: A new version of a library (e.g., pandas 3.0) might introduce "breaking changes" that would cause your code, which was written for version 2.1.2, to fail.
  • Consistency: It ensures that the code you write today will still work with the same dependencies six months from now.
  • Reproducibility: It's the only way to guarantee that the project environment can be perfectly recreated.

pip freeze automatically pins the versions for you, which is why it's the standard tool for this job.

✨ Conclusion & Key Takeaways​

Using a requirements.txt file is not just a best practice; it's a fundamental part of modern Python development. It provides a reliable, reproducible way to manage your project's dependencies.

Let's summarize the key takeaways:

  • Dependencies are a project's external libraries.
  • requirements.txt lists all dependencies and their exact versions.
  • pip freeze > requirements.txt is the command to generate the file.
  • pip install -r requirements.txt is the command to install all dependencies from the file.
  • Always pin versions (==) to ensure your project is stable and reproducible.

Challenge Yourself:

  1. Create a new project folder.
  2. Install two packages you find interesting from PyPI (e.g., requests and beautifulsoup4).
  3. Generate a requirements.txt file for your project.
  4. Open the requirements.txt file and see how pip freeze has listed the packages and their dependencies with pinned versions.

➡️ Next Steps​

Installing all your packages into your main Python installation can get messy, especially when you work on multiple projects that might need different versions of the same library. The solution is to create isolated environments for each project. In our final article of this series, we'll learn how to do just that with "Virtual Environments: Isolating Project Dependencies."

Happy coding!