Virtual Environments: Managing Project Dependencies with Python

Previously in this course, we covered importing standard modules to extend the functionality of your scripts. Now that we are about to start using third-party packages, we need a way to keep those packages organized so they don't interfere with your global Python installation or other projects. This lesson introduces venv, the industry standard for environment management.

Why Do We Need Virtual Environments?

When you install a Python library, it typically goes into a global directory on your machine. If Project A needs version 1.0 of a library and Project B needs version 2.0, you have a problem: you can only have one version installed globally.

A virtual environment is a self-contained directory tree that includes a Python installation and a copy of the pip tool. It creates an isolated sandbox for your project. Any package you install while the environment is active stays inside that sandbox, leaving your global system untouched.

Creating and Activating an Environment

The venv module comes built-in with modern Python. To set one up for your project, navigate to your project folder in your terminal and run the following command:

Bash
# Create the environment in a folder named 'venv'
python -m venv venv

Once the command finishes, you will see a new folder named venv in your directory. To start using it, you must "activate" it, which tells your terminal to prioritize the Python and pip located inside that folder over the system-wide versions.

On macOS/Linux:

Bash
source venv/bin/activate

On Windows:

Bash
.\venv\Scripts\activate

Once activated, you will usually see (venv) appear at the start of your command prompt. You are now working inside your isolated environment.

Installing Packages with Pip

pip is the standard package manager for Python. When you are inside an active virtual environment, any package you install via pip is local to that specific project.

To install a package, use the pip install command. Let's install a popular package as an example:

Bash
# Install the 'requests' library
pip install requests

If you ever need to see what packages are currently installed in your environment, use:

Bash
pip list

Managing Dependencies

As your project grows, you will eventually want to share your code with others or deploy it to a server. To ensure the environment is reproducible, we use a requirements.txt file.

1. Save your dependencies:

   Bash
   pip freeze > requirements.txt
   

2. Install from a file: If you download a project that has a requirements.txt file, you can install everything it needs at once:

   Bash
   pip install -r requirements.txt
   

Hands-on Exercise

1. Create a new directory for a test project.
2. Create and activate a virtual environment named venv.
3. Use pip install to add the requests library.
4. Run pip list to confirm it appears in the output.
5. Create a requirements.txt file using the pip freeze command and inspect its contents with a text editor.
6. Deactivate the environment by simply typing deactivate in your terminal.

Common Pitfalls

• Forgetting to activate: If you run pip install and get a "Permission Denied" error, you are likely not in a virtual environment and are trying to modify system files. Always check for the (venv) prefix in your terminal.
• Committing the environment: Never add your venv folder to version control (like Git). It contains thousands of files specific to your machine's path. Only commit your requirements.txt file.
• Mixing environments: If you open a new terminal tab, your environment is not active by default. You must run the source or activate command again for every new terminal window.

FAQ

Q: Can I delete the venv folder? A: Yes. If you delete the folder, you lose the isolated environment and the installed packages. Since you have your requirements.txt, you can recreate it at any time by running pip install -r requirements.txt.

Q: Do I need a separate environment for every single script? A: Not necessarily. Most developers use one virtual environment per project folder.

Q: Is venv the only way to manage environments? A: venv is the standard tool built into Python. While tools like conda or poetry exist, venv is the best place to start for beginners to understand the underlying mechanics of environment management.

Recap

Virtual environments are essential for maintaining clean, reproducible Python projects. By using python -m venv to isolate your work and pip to manage dependencies, you ensure that your code will run consistently regardless of the system it is installed on. You've now secured your project structure, which is a critical step before we start working with external APIs.

Up next: Using Third-Party Libraries