Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 1

Virtual Environments and Dependency Management

Recommended resources

Hello! Welcome to the first lesson in our course on building an agentic AI for web application testing.

To kick things off, we're going to establish a critical foundation for all the Python development we'll be doing: managing your development environment. As someone with extensive experience in software testing, you know how crucial it is to have a clean, controlled, and reproducible environment to ensure your tests are reliable. A small difference in a library version can lead to flaky tests and hours of debugging.

In the Python world, we achieve this control using virtual environments. This lesson will show you how to set up these isolated environments and manage your project's external libraries—known as dependencies—using pip and a requirements.txt file. Mastering this is the first essential step toward building our robust testing agent.

Why Do We Need Virtual Environments?

Before we dive into the commands, let's understand why this is a non-negotiable best practice in Python. Imagine you are working on two different projects:

  1. A legacy application that requires an older version of a library (e.g., requests==2.20.0).
  2. Our new AI agent, which needs the latest features from a newer version of the same library (e.g., requests==2.31.0).

If you install these libraries globally on your computer, you can only have one version at a time. The second installation would overwrite the first, breaking one of your projects. This is often called "dependency hell."

Virtual environments solve this by creating an isolated, self-contained directory for each project, with its own Python interpreter and its own set of installed libraries. This prevents conflicts and ensures your project is portable and reproducible.

To explore this further, the following article provides an excellent overview of the problems virtual environments solve.

Python Virtual Environments: A Primer

This article from Real Python clearly explains the key reasons for using virtual environments. Understanding these motivations will make the practical steps that follow more meaningful.

Please read the section titled 'Why Do You Need Virtual Environments?'. Focus on the three main problems it discusses: dependency conflicts, system pollution, and reproducibility issues.

In short, a virtual environment is a folder that contains everything a specific project needs to run, keeping it separate from all other projects on your system.

This diagram shows the main components of a Python virtual environment: an independent Python interpreter, its own package installer (pip), activation scripts to switch into the environment, and a local site-packages directory where project-specific libraries are stored.

Creating and Using a Virtual Environment with venv

Python comes with a built-in module called venv for creating virtual environments. It's the standard, recommended tool for this job. The workflow is straightforward: create, activate, and you're ready to go.

Here's the step-by-step process.

Python Virtual Environments: A Primer

Now for the practical part. This section of the same Real Python article provides clear, step-by-step instructions for creating, activating, and deactivating a virtual environment. It includes the specific commands for Windows, Linux, and macOS.

Follow the steps under 'How Can You Work With a Python Virtual Environment?'. Specifically, read and execute the commands in the subsections 'Create It', 'Activate It', and 'Deactivate It'. A common convention is to name your environment folder .venv or venv.

Let's summarize the key commands from the article:

  1. Navigate to your project folder in your terminal.
  2. Create the environment: 
    # For Windows
py -m venv venv

# For macOS/Linux
python3 -m venv venv
    This command creates a new directory named venv in your project folder.
*This screenshot shows the command to create a virtual environment in PowerShell and the resulting directory structure. The `Scripts` directory (or `bin` on macOS/Linux) contains the environment's Python and pip executables, while `Lib/site-packages` is where dependencies will be installed.*

3. Activate the environment:
```bash
# For Windows (PowerShell)
.\venv\Scripts\activate

# For macOS/Linux (bash/zsh)
source venv/bin/activate
```
After activation, you'll see the environment's name (e.g., `(venv)`) at the beginning of your terminal prompt. This indicates that any Python or `pip` commands will now use the executables inside the `venv` folder.

4. Deactivate the environment:
When you're done working, simply run:
bash deactivate
This command returns you to your system's default shell environment.

Test your understanding!

You have a project in a folder named my-agent-project. You want to create a virtual environment inside it named .venv. After creating and activating it, how would you confirm that your terminal is indeed using the Python interpreter from the virtual environment and not the global system Python?

Show answer

After activating the environment, you can run one of the following commands:

  • On macOS/Linux: which python
  • On Windows: where python

The output should show a path that points inside your my-agent-project/.venv/ directory. For example: /path/to/my-agent-project/.venv/bin/python. This confirms that the python command is now linked to the local interpreter in your virtual environment.

Managing Dependencies with pip and requirements.txt

With an active virtual environment, you can now install packages for your project. The tool for this is pip, the Python Package Installer.

If you have experience with JavaScript and Playwright, you'll find this process very similar to using npm or yarn with a package.json file. In Python, the standard convention is to use a requirements.txt file.

Installing Packages

To install a package, you use the pip install command. For example, in later lessons, we will be using the openai library to interact with LLMs. To install it, you would run:

pip install openai

pip will download openai and any other packages it depends on (its "dependencies") from the Python Package Index (PyPI) and install them into your virtual environment's site-packages directory.

Recording Dependencies

To ensure your project is reproducible, you must save a list of its dependencies. The standard way to do this is with pip freeze. This command outputs a list of all packages installed in the current environment with their exact versions.

You can redirect this output to a file, conventionally named requirements.txt:

pip freeze > requirements.txt

Your requirements.txt file will look something like this:

openai==1.12.0
httpx==0.27.0
...

This file is your project's recipe. You should commit it to your version control system (like Git).

Reproducing an Environment

Now, if another developer (or a CI/CD server like GitHub Actions) wants to set up your project, they can create and activate a new virtual environment and install the exact same dependencies by running:

pip install -r requirements.txt

This command tells pip to read the requirements.txt file and install all the listed packages at their specified versions, perfectly recreating the development environment.

The official Python Packaging guide provides a concise reference for this workflow.

Install packages in a virtual environment using pip and venv

The official Python Packaging guide offers a straightforward walkthrough of using pip and a requirements.txt file. This reinforces the workflow we just discussed.

Please read the sections 'Using a requirements file' and 'Freezing dependencies'. These explain how to create a requirements.txt file and how to install from it.

Practice Exercise

Follow these steps to practice the full workflow:

  1. Create a new directory for a practice project (e.g., practice-project).
  2. Navigate into that directory.
  3. Create a virtual environment named venv.
  4. Activate it.
  5. Install the requests library: pip install requests.
  6. Generate a requirements.txt file that includes requests and its dependencies.
  7. Deactivate the environment.
  8. (Optional bonus) Delete the venv folder to simulate moving to a new machine. Create a new virtual environment, activate it, and use your requirements.txt file to reinstall the packages. Check that requests is installed using pip freeze.
Show solution steps

Here are the commands you would run (using macOS/Linux syntax):

  1. mkdir practice-project
  2. cd practice-project
  3. python3 -m venv venv
  4. source venv/bin/activate
  5. pip install requests
  6. pip freeze > requirements.txt
  7. deactivate

Bonus steps:

  1. rm -rf venv (be careful with this command!)
  2. python3 -m venv venv
  3. source venv/bin/activate
  4. pip install -r requirements.txt
  5. pip freeze (You should see requests and its dependencies in the output).

Conclusion

Congratulations on completing your first lesson! You've established a foundational skill for all modern Python development.

Here are the key takeaways:

  • Isolation is Key: Virtual environments, created with venv, isolate your project's dependencies to prevent conflicts and ensure reproducibility.
  • The Workflow: The core cycle is to create (python -m venv venv), activate (source venv/bin/activate or .\venv\Scripts\activate), and then work within the environment.
  • Dependency Management: pip is used to install packages.
  • Reproducibility: You record your environment's state with pip freeze > requirements.txt and recreate it elsewhere with pip install -r requirements.txt.

This disciplined approach will save you countless hours of debugging down the road as we build our increasingly complex agentic AI tester.

In our next lesson, we will dive into manipulating complex data structures like nested dictionaries and lists. Now that our environment is set up, we need to learn how to work with the data we'll be receiving from web APIs and large language models, which is often structured in this way.