How to Generate a requirements.txt File for an Existing Python Project

Introduction

When working on Python projects, managing dependencies is crucial for ensuring that your code runs consistently across different environments. The standard way to document these dependencies is through a requirements.txt file, which lists all the packages your project needs along with their versions.

In this article, I'll show you two different approaches to generate a requirements.txt file for an existing Python project:

Using virtual environments with pip freeze
Using pipreqs to scan actual imports in your code

Each method has its advantages and use cases, so let's explore both to help you choose the right approach for your project.

Using Virtual Environments with pip freeze

The most common approach to generating a requirements.txt file is using pip freeze within a virtual environment. This method captures all installed packages in your current environment.

Step 1: Activate Your Virtual Environment

First, ensure that all the dependencies of your project are installed in your current environment. If you're using a virtual environment (which is recommended), activate it first:

1# For virtual environment activation on macOS/Linux
2source venv/bin/activate
3
4# On Windows
5.\venv\Scripts\activate

Step 2: Generate requirements.txt

Use pip freeze to list all the installed packages and their versions, and redirect the output to a requirements.txt file:

1pip freeze > requirements.txt

This command will create a requirements.txt file in your project directory containing a list of all installed packages and their versions.

Virtual Environment Best Practice

It's good practice to use a virtual environment for your project to isolate its dependencies. You can create one using Python's built-in venv module:

python -m venv venv

Using pipreqs to Scan Actual Imports

While pip freeze captures all installed packages, it might include dependencies that aren't actually used in your project. To generate a requirements.txt file that only includes libraries actually used in your project's code files, you can use a tool called pipreqs.

Step 1: Install pipreqs

You need to install pipreqs if you haven't already:

1pip install pipreqs

Step 2: Run pipreqs on Your Project Directory

Use pipreqs to generate the requirements.txt file:

1# Navigate to your project directory
2cd /path/to/your/project
3
4# Run pipreqs
5pipreqs .

The . indicates the current directory. This will scan your project's files and generate a requirements.txt file with only the necessary packages.

Additional Options

If you want to overwrite an existing requirements.txt file, use the --force option:

1pipreqs . --force

If you encounter any issues or need help with the pipreqs command, you can check its help documentation:

1pipreqs --help

Advantages of pipreqs

Using pipreqs ensures that your requirements.txt file is accurate and only includes the libraries that your project truly depends on, making it more efficient and easier to manage.

Comparing Both Methods

pip freeze

Captures all installed packages in the environment
May include unnecessary dependencies
Simple and straightforward to use
Ensures exact version matching
Best for environments where all packages are relevant

pipreqs

Only includes packages actually imported in your code
Creates a leaner requirements file
May miss dynamically imported packages
Requires an additional installation
Best for projects with many dependencies where only some are used

Choose the method that best fits your project's needs. If you're working in a clean virtual environment specifically set up for your project, pip freeze might be sufficient. If you're working in an environment with many packages and want to ensure a minimal dependency list, pipreqs is the better choice.

Conclusion

Generating a requirements.txt file is an essential step in making your Python projects reproducible and shareable. Whether you choose to use pip freeze with a virtual environment or pipreqs to scan your actual imports, having a well-maintained requirements file will make it easier for others (and your future self) to set up and run your project.

Remember that dependency management is an ongoing process. As your project evolves, make sure to update your requirements.txt file to reflect any new dependencies or version changes.