No More Dependency Errors: Running Our Project with Virtual Environments

Setting up a project locally should be simple. But in reality, many developers have experienced dependency conflicts, package installation failures, version mismatches, or the infamous “it works on my machine” problem.

During one of our Python-based projects, we quickly realized that managing dependencies globally on our machines was creating unnecessary issues. Different Python versions, incompatible package updates, and missing libraries were slowing down development and confusing team members.

That’s when we decided to standardize our local setup process using Python virtual environments.

In this article, I’ll walk through our complete workflow for running a project locally using a virtual environment, why we adopted this approach, the problems it solved, and some practical lessons we learned along the way.

The Problem We Faced

At the beginning of our project, everyone on the team had slightly different development environments.

Some developers had:

• Different Python versions
• Different package versions
• Globally installed libraries
• Existing configurations from older projects

Initially, everything seemed fine. But as the project grew, problems started appearing.

One team member would install a package update that accidentally broke compatibility with another library. Another developer would run the project successfully, while someone else received import errors or dependency conflicts.

The most common issue was this:

ModuleNotFoundError

Or sometimes:

Version conflict detected

These issues became repetitive and frustrating.

We realized that if every developer used their own global Python environment, maintaining consistency would become nearly impossible.

So we switched to using a virtual environment for the project.

What is a Virtual Environment?

A virtual environment is an isolated Python environment created specifically for a project.

Instead of installing packages globally across your entire operating system, the virtual environment keeps all project dependencies inside a dedicated folder.

Think of it as creating a separate workspace for your project where:

• Dependencies remain isolated
• Package versions stay consistent
• Other projects are unaffected
• Team collaboration becomes easier

This approach solved most of our dependency-related problems immediately.

Why Virtual Environments Matter in Real Projects

For small personal scripts, global installations may seem manageable. But for real-world applications, virtual environments are almost essential.

Here’s why they became important in our workflow.

1. Preventing Dependency Conflicts

Different projects often require different versions of the same package.

For example:

• Project A may need numpy==1.24
• Project B may require numpy==2.0

Installing both globally can create conflicts.

With virtual environments, each project maintains its own dependency versions independently.

2. Easier Team Collaboration

When multiple developers work on the same project, consistency matters.

Using a shared requirements.txt file allowed every team member to install the exact same package versions.

This reduced environment-related bugs significantly.

3. Cleaner Development Environment

Without virtual environments, your global Python installation eventually becomes cluttered with unused libraries.

A virtual environment keeps the system clean and organized.

4. Better Deployment Consistency

The local setup process also becomes closer to production deployment environments.

This minimizes surprises when deploying applications to servers or cloud platforms.

Our Local Project Setup Workflow

Here’s the exact process we followed when setting up the project locally.

Step 1 — Installing Prerequisites

Before cloning the project, we ensured the following tools were installed:

• Python
• Git
• Visual Studio Code (or another IDE)

To verify Python installation:

python --version

To verify pip:

pip --version

We also made sure everyone used the same Python version to avoid compatibility issues.

Step 2 — Cloning the Repository

We cloned the project repository from GitHub.

git clone <repository-link>

Then navigated into the project directory.

cd project-name

This gave us access to the source code and project files.

Step 3 — Creating the Virtual Environment

Next, we created a virtual environment using Python’s built-in venv module.

python -m venv venv

This generated a new folder named venv.

Inside this folder, Python creates:

• A separate interpreter
• Local package storage
• Activation scripts
• Isolated dependency management

This environment becomes completely independent from the system-wide Python installation.

Step 4 — Activating the Environment

After creation, we activated the environment.

On Windows

venv\Scripts\activate

On macOS/Linux

source venv/bin/activate

Once activated, the terminal changes like this:

(venv)

This indicates that all package installations and Python commands are now isolated inside the virtual environment.

This step is extremely important because forgetting to activate the environment can cause packages to install globally by mistake.

Step 5 — Installing Dependencies

After activation, we installed all required packages.

pip install -r requirements.txt

The requirements.txt file contains all dependencies needed for the project.

For example:

numpy
pandas
torch
transformers
flask

Using this file ensured every developer worked with the same environment setup.

Step 6 — Running the Project

Once installation completed successfully, we ran the project.

Depending on the project structure:

python app.py

or

python main.py

At this stage, the application started successfully on the local machine.

For web applications, we could usually access the project through:

http://localhost:5000

or another configured port.

Common Problems We Encountered

Even with virtual environments, we still faced several setup challenges.

Here are the most common ones and how we solved them.

1. Package Build Errors

Some libraries failed during installation.

Example:

ERROR: Failed building wheel for tokenizers

This usually happened because:

• pip was outdated
• build tools were missing
• Python versions were incompatible

We fixed this by upgrading pip first.

python -m pip install --upgrade pip

In some cases, reinstalling Visual C++ Build Tools also helped on Windows.

2. Activation Script Disabled

On Windows PowerShell, script execution may be blocked.

We solved this using:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

After restarting PowerShell, activation worked correctly.

3. Missing Modules

Sometimes developers forgot to install dependencies before running the project.

This produced errors like:

ModuleNotFoundError

The solution was simply:

pip install -r requirements.txt

4. Wrong Python Version

Some packages behaved differently across Python versions.

To avoid this, we standardized one Python version for the entire project.

This improved stability significantly.

Best Practices We Followed

Over time, we adopted several best practices that made development smoother.

Always Use requirements.txt

Whenever new packages were added:

pip freeze > requirements.txt

This kept dependency tracking updated.

Never Commit the venv Folder

The virtual environment folder should not be pushed to GitHub.

We added it to .gitignore.

venv/

This prevented unnecessary large uploads.

Keep Environments Lightweight

We avoided installing unnecessary packages to keep the environment clean and manageable.

Use Consistent Naming

Most developers use:

venv

as the environment folder name because it is simple and widely recognized.

Final Thoughts

A proper local setup workflow is one of the most underrated parts of software development.

Without environmental management, even simple projects can become difficult to maintain as they grow.

Using Python virtual environments helped our team create a cleaner, more reliable, and more professional development process.

If you are starting any Python project, whether personal, academic, or professional, setting up a virtual environment should be one of your first steps.

It may seem small initially, but it saves countless hours of debugging later.

Thanks for sticking till the end!

Any feedback or corrections are truly welcome!