You Just Wrote a Python Script, Now What?
You’ve spent hours crafting the perfect Python script. It runs flawlessly on your machine, pulling data, processing images, or automating a tedious task. You’re ready to share your masterpiece with a colleague, deploy it to a server, or simply ensure you can run it again next month. You send over the .py file, they excitedly run it, and are immediately greeted by a wall of red text: “ModuleNotFoundError: No module named ‘requests'”.
This frustrating scenario is a rite of passage for Python developers. Your code depends on external libraries—packages like requests, pandas, numpy, or beautifulsoup4—that aren’t part of Python’s standard library. While you have them installed, anyone else trying to run your code does not. Manually listing every package in a README is error-prone and tedious.
This is where the humble requirements.txt file becomes your project’s best friend. It’s a simple text file that acts as a manifest, a recipe, and a contract for your Python project’s dependencies. Creating one is a fundamental skill that separates a quick script from a shareable, reproducible project.
Understanding the Role of Requirements.txt
Think of requirements.txt as the ingredient list for your Python project. Just as a recipe needs specific amounts of flour, sugar, and eggs, your project needs specific versions of libraries to function correctly. This file serves several critical purposes.
First, it ensures reproducibility. By pinning exact versions of dependencies, you guarantee that your project will behave the same way on your laptop, your teammate’s desktop, and a production server, today and six months from now. Without it, someone installing the “latest” version of a library might get a new release that breaks your code.
Second, it simplifies setup. Instead of a long, complicated installation guide, you provide a single command: pip install -r requirements.txt. This command tells Python’s package installer, pip, to read the file and install every listed package automatically. It’s a one-step setup process.
Finally, it acts as documentation. By glancing at requirements.txt, other developers (or your future self) instantly understand what external tools your project relies on, providing insight into its capabilities and architecture.
The Prerequisites on Your System
Before you generate your first requirements file, you need two core tools: Python and pip. Most modern Python installations include pip by default. You can verify both are installed and check their versions by opening your terminal or command prompt.
Run the command python –version or python3 –version to see your Python version. Then, run pip –version or pip3 –version. If you see version numbers, you’re ready to proceed. If you get a “command not found” error, you’ll need to install Python from the official python.org website, ensuring you check the box to “Add Python to PATH” during installation on Windows.
It’s also crucial that you’re working within the correct Python environment. If you use virtual environments—a highly recommended practice to isolate project dependencies—make sure you have activated the environment for your project before generating the requirements file. This ensures you only capture the packages specific to that project, not every package installed globally on your system.
Generating Requirements.txt from Your Current Environment
The most straightforward method to create a requirements.txt file is to generate it from the packages already installed in your active Python environment. This is perfect when you’ve been developing a project and have iteratively installed what you need.
Navigate to your project’s root directory in your terminal. This is the folder containing your main .py scripts. Once there, run a single command.
The classic and most reliable command is pip freeze. This command outputs a list of all installed packages in the format `package==version`. To save this list directly to a file named requirements.txt, you use output redirection.
Run: pip freeze > requirements.txt
That’s it. The `>` symbol tells your shell to take the output of `pip freeze` and write it into a new file called requirements.txt. If the file already exists, this command will overwrite it. Let’s examine what the generated file looks like.
Open the newly created requirements.txt file in your text editor. You’ll see entries like this, one per line.
- requests==2.31.0
- pandas==2.1.3
- numpy==1.24.3
- python-dotenv==1.0.0
Each line follows the `package==version` format. This is the format pip understands when performing an install. The version pinning (using `==`) is what guarantees reproducibility. Anyone using this file will get the exact same versions you have.
When Pip Freeze is Too Much
The `pip freeze` method has one significant drawback: it lists every single package in your environment, including transitive dependencies—packages that your direct dependencies need to run. Your project might use `requests`, but `pip freeze` will also list `urllib3`, `charset-normalizer`, `idna`, and `certifi` because requests depends on them.
This can clutter your requirements.txt with dozens of low-level packages you didn’t explicitly choose. While it still works, it makes the file harder for humans to read and can sometimes lead to version conflicts if a transitive dependency is pinned in a way that interferes with another package’s needs.
For more control and a cleaner file, you can manually create and maintain requirements.txt. Open a new text file in your project root and name it requirements.txt. Inside, list only the top-level packages your project directly imports, optionally with version specifiers.
For example, a cleaner, intentional requirements.txt might look like this.
- requests>=2.28.0
- pandas==2.1.3
- flask
- psycopg2-binary
Here, `requests>=2.28.0` specifies a minimum version but allows newer, compatible ones. `pandas==2.1.3` pins an exact version. `flask` with no version will install the latest available, which is less reproducible but common for early-stage projects. This manual approach puts you in charge but requires you to remember to update the file when you add a new dependency.
Using Pipreqs for a Smart, Project-Specific List
There’s a powerful middle ground between the exhaustive `pip freeze` and fully manual management: a tool called `pipreqs`. This tool scans your actual Python source code (.py files) for import statements and generates a requirements.txt file containing only the packages your code explicitly uses.
This is often the ideal approach. It automatically ignores packages you have installed but aren’t using, resulting in a lean, accurate dependency list. First, you need to install pipreqs itself. Since it’s a tool for managing projects, it’s often installed globally.
Run: pip install pipreqs
Once installed, navigate to your project directory in the terminal. To generate the requirements.txt file, run the following command.
Run: pipreqs . –force
The dot `.` tells pipreqs to scan the current directory. The `–force` flag is useful if a requirements.txt file already exists and you want to overwrite it. Without `–force`, pipreqs will refuse to write if the file is already present.
Pipreqs will crawl through your .py files, identify imports like `import requests`, `from pandas import DataFrame`, and write the corresponding package names to requirements.txt. By default, it does not pin versions unless you use the `–mode` flag, which can help with compatibility. The output is a clean, human-readable file containing just what your project needs.
Installing Dependencies from a Requirements File
Creating the file is only half the battle. The other half is using it to set up an environment. This is the payoff for your work. Whether you’re onboarding a new team member or deploying to a fresh server, the setup process is standardized.
The best practice is to first create a new, isolated virtual environment for the project. This prevents package conflicts between different projects. Once the virtual environment is created and activated, you use pip to read the requirements file.
The command is simple: pip install -r requirements.txt
The `-r` flag tells pip to install from a “requirements file.” Pip will read requirements.txt line by line, download each specified package (and its dependencies) from the Python Package Index (PyPI), and install them into the active environment. You’ll see a stream of output as each package is collected and installed. When it finishes, the environment will mirror the one the project was developed in, and you can run the code without import errors.
Handling Version Conflicts and Failed Installations
Sometimes, running `pip install -r requirements.txt` can fail. The most common cause is a version conflict. This happens when two packages in your file require incompatible versions of the same underlying dependency. For example, PackageA might need `numpy<2.0` while PackageB needs `numpy>=2.0`. Pip cannot satisfy both constraints simultaneously.
The error message will usually point to the conflicting packages. Your first step is to check if newer, compatible versions of your direct dependencies are available. You can try relaxing version pins in your requirements.txt. Change exact pins (`==`) to compatible ranges (`>=`) and try the install again.
If the conflict is deep and unresolvable, you may need to find alternative packages that provide similar functionality but with different dependencies. In complex cases, using a more advanced dependency resolver like the one built into `pip` itself (with the `–use-feature=2020-resolver` flag in newer versions) or a tool like `poetry` or `pipenv` can help, though these are topics for more advanced dependency management.
Another common issue is a package that isn’t available on PyPI, perhaps because it’s a private, internal company package or it’s installed from a version control system (VCS) like GitHub. For these cases, requirements.txt supports alternative formats.
You can specify a VCS link directly in the file.
- -e git+https://github.com/username/repo.git@main#egg=package_name
Or, for a local directory (useful during development).
- -e /path/to/your/local/package
The `-e` flag stands for “editable” mode, which links the package directly into your environment, allowing you to make changes to the source code and have them reflect immediately without reinstallation.
Best Practices for Maintaining Your Requirements
A requirements.txt file is not a “set it and forget it” artifact. As your project evolves, you’ll add new features and, consequently, new dependencies. Letting the file become outdated is a common source of “it works on my machine” problems.
Establish a simple workflow. Whenever you install a new package for your project using `pip install some-new-package`, immediately update your requirements.txt file. You can do this by running `pip freeze > requirements.txt` again if you use that method, or by manually adding the new package name to your curated list.
For teams, it’s wise to occasionally “audit” your dependencies. Use the command `pip list –outdated` to see which installed packages have newer versions available. Updating can bring performance improvements, security patches, and new features, but it also carries risk. The safest approach is to update one package at a time, then run your project’s full test suite to ensure nothing breaks.
Consider splitting your requirements into multiple files for complex projects. A common pattern is to have a `requirements-dev.txt` for development-only tools like linters (`flake8`), formatters (`black`), and test frameworks (`pytest`). Your core `requirements.txt` would then only contain what’s needed for the application to run in production. You can install the dev dependencies with `pip install -r requirements-dev.txt`.
When to Graduate to More Advanced Tools
The requirements.txt file is the standard, universal tool for Python dependency management, and it’s sufficient for most projects. However, for large, complex applications with many interdependent packages, you might encounter its limitations: manual version conflict resolution, the separation of dependencies from virtual environment management, and a lack of deterministic builds.
This is where next-generation tools like Poetry and Pipenv come in. These tools combine dependency management, virtual environment handling, and packaging into a single, cohesive workflow. They use a different file (like `pyproject.toml` for Poetry) that can define dependencies with more sophisticated version ranges and automatically lock them into a precise, reproducible state in a separate lock file.
If you find yourself constantly battling version conflicts in a large team, or if you’re building a library to be distributed to others, exploring these tools is a logical next step. For the vast majority of scripts, web apps, and data science projects, a well-maintained requirements.txt file remains the perfect, simple solution.
Your Project is Now Portable and Professional
By taking the few minutes required to create and maintain a requirements.txt file, you’ve fundamentally upgraded your Python project. You’ve moved from a fragile collection of scripts that only works in one specific environment to a robust, shareable piece of software. The barrier to entry for collaborators has dropped to a single command.
The process is straightforward. Generate the file with `pip freeze`, craft it manually, or use `pipreqs` for a smart scan. Use a virtual environment to isolate your project’s dependencies. Install them anywhere with `pip install -r requirements.txt`. Update the file diligently as your project grows.
This simple text file is more than just a list; it’s a commitment to reproducibility, a courtesy to other developers, and a hallmark of professional Python development. Start creating one for every project, and you’ll never again hear the dreaded words, “It doesn’t work on my computer.”
