4 - Virtualenv

What a Virtual Environment Is

When I install a Python package with pip3 install ansible, it goes into the system-wide Python installation at /usr/lib/python3/. Every Python script on the entire Ubuntu VM now shares that installation. This sounds convenient until it isn’t.

Here’s the problem: different projects need different versions of the same package.

Project A (ansible-network):   needs ansible==9.x, netmiko==4.x
Project B (legacy-scripts):    needs ansible==2.9, netmiko==3.x
System tools (apt, Ubuntu):    need specific Python packages to function

If I install everything into the system Python, these projects will constantly conflict. Upgrading Ansible for Project A breaks Project B. Worse, a bad pip install can break Ubuntu’s own system tools that depend on Python.

A virtual environment solves this by creating a completely isolated Python installation for each project:

/home/ansible/
├── venvs/
│   ├── ansible-network/      # Isolated Python for this guide's project
│   │   ├── bin/python3       # Its own Python interpreter
│   │   ├── bin/pip           # Its own pip
│   │   ├── bin/ansible       # Ansible installed HERE, not system-wide
│   │   └── lib/              # All packages installed here
│   └── legacy-scripts/       # Completely separate environment
│       ├── bin/python3
│       └── lib/
└── projects/
    └── ansible-network/      # My project code lives here (not inside venvs/)

When I activate a virtual environment, my shell uses that environment’s Python and pip instead of the system ones. When I deactivate it, the system Python comes back. Nothing ever collides.

venv vs virtualenv

Both tools create virtual environments, but they come from different places and have slightly different capabilities.

venv Python’s Built-in Tool

venv is included with Python 3.3+ and ships with Ubuntu 22.04. No installation required. It’s the official, standard way to create virtual environments and covers everything I need.

How to check if venv is available:

python3 -m venv --help

Limitations of venv:

• Cannot create environments for Python versions other than the one it’s called from
• Slightly fewer configuration options than virtualenv

virtualenv The Third-Party Tool

virtualenv is a more mature, feature-rich third-party package that predates Python’s built-in venv. It’s what most older documentation and enterprise tooling references when they say “virtual environment.”

How to install and check version:

pip3 install virtualenv --break-system-packages
virtualenv --version

Additional capabilities of virtualenv:

• Can create environments for different Python versions (e.g., virtualenv -p python3.9 myenv)
• Faster environment creation
• More configuration options
• Required by some tools like tox (a testing framework)

Comparison

Checking What’s Already Installed

Check Python version:

python3 --version

Check Pip version:

pip3 --version

Check if venv module is available:

python3 -m venv --help 2>&1 | head -5

Installing pip and venv

On a fresh Ubuntu 22.04 install, I run:

sudo apt update
sudo apt install -y python3-pip python3-venv

• python3-pip — installs pip3, the package installer for Python 3
• python3-venv — installs the venv module (sometimes missing on minimal Ubuntu installs)

Upgrading pip Itself

pip has its own updates. Before creating any environments, I upgrade pip:

pip3 install --upgrade pip --break-system-packages

Installing virtualenv

Even though I’ll primarily use venv for this project, I install virtualenv to have both available:

pip3 install virtualenv --break-system-packages
virtualenv --version

Creating the Environment with venv

First, I create the venvs directory:

mkdir -p ~/venvs

Then I create the virtual environment:

python3 -m venv ~/venvs/ansible-network

• python3 -m venv - runs the venv module using Python 3
• ~/venvs/ansible-network - the path where the environment will be created

What Gets Created

tree ~/venvs/ansible-network/ -L 3

/home/ansible/venvs/ansible-network/
├── bin/
│   ├── activate            # The activation script I'll source
│   ├── activate.fish       # Activation script for Fish shell
│   ├── pip                 # pip linked to this environment
│   ├── pip3                # Same as pip
│   ├── python              # Python interpreter for this environment
│   └── python3             # Same as python
├── include/                # C headers for compiling extensions
├── lib/
│   └── python3.10/
│       └── site-packages/  # Installed packages go here
└── pyvenv.cfg              # Environment configuration file

pyvenv.cfg is worth looking at:

cat ~/venvs/ansible-network/pyvenv.cfg

home = /usr/bin
include-system-site-packages = false
version = 3.10.12

The include-system-site-packages = false line means this environment is completely isolated from the system Python packages. Nothing installed system-wide bleeds in.

Creating the Same Environment with virtualenv (Alternative)

Use virtualenv instead of venv:

virtualenv ~/venvs/ansible-network-v2

Target a sepcific Python version with virtualenv:

virtualenv -p python3.10 ~/venvs/ansible-network-v3

• -p python3.10 - tells virtualenv which Python binary to use. This is the main advantage over venv since I can target any installed Python version.

Approach 1: Name After the Project

python3 -m venv ~/venvs/ansible-network
python3 -m venv ~/venvs/netbox-scripts
python3 -m venv ~/venvs/legacy-automation

When to use this: When I have multiple projects with different dependency requirements. Each project gets its own environment. The name makes it immediately obvious which project the environment belongs to.

Pros:

• Clear association between environment and project
• Easy to manage when working on multiple projects
• Aligns with the “one virtualenv per project” best practice

Cons:

• If I rename the project, the environment name becomes confusing
• Managing many environments requires discipline

Approach 2: Generic Name

python3 -m venv ~/venvs/ansible-env
python3 -m venv ~/venvs/python-env

When to use this: When I have one general-purpose environment for all Ansible work, or on a dedicated Ansible control node that only ever runs one type of workload.

Pros:

• Simple, one environment to rule them all
• Common in CI/CD pipelines where the environment name doesn’t matter

Cons:

• Over time, the environment accumulates packages from multiple projects
• Hard to tell which packages are actually needed vs. installed by accident
• requirements.txt becomes bloated

My Convention for This Lab

For this lab I use the project-specific naming approach:

python3 -m venv ~/venvs/ansible-network

This environment is dedicated to this project. When I start a new, separate project later, it gets its own environment.

Activating

source ~/venvs/ansible-network/bin/activate

• source - runs the activation script in the current shell session (not a subprocess). The environment variables set by activate wouldn’t affect my current shell.
• After activation, my shell prompt changes to show the environment name:

# Before activation
ansible@ubuntu:~$

# After activation
(ansible-network) ansible@ubuntu:~$

That (ansible-network) prefix is my visual confirmation that I’m inside the right environment.

Confirming the Activation Worked

Check where Python is coming from:

which python3

Expected output:

# /home/ansible/venvs/ansible-network/bin/python3

Check where pip coming from:

which pip

Expected output:

# /home/ansible/venvs/ansible-network/bin/pip

Check whhat packages are currently installed:

pip list

Example output:

# Package    Version
# ---------- -------
# pip        24.x.x
# setuptools 68.x.x

Deactivating

deactivate

My prompt returns to normal and Python/pip point back to the system installation.

which python3

Expected output:

# /usr/bin/python3  ← back to system Python

Automating Activation

I can add the activation command to my ~/.bashrc so it activates automatically on every new shell:

echo "source ~/venvs/ansible-network/bin/activate" >> ~/.bashrc
source ~/.bashrc

Upgrading pip

I always upgrade pip inside a fresh virtualenv before installing anything.

pip install --upgrade pip

Installing the Core Stack

I’ll install everything in a logical order, explaining what each package is and why I need it.

Core Ansible:

pip install ansible

Ansible linting and validation tools.

pip install ansible-lint
pip install yamllint

SSH connectivity libraries:

pip install paramiko
pip install netmiko

Vendor-neutral network abstraction:

pip install napalm

HTTP library for REST APIs (Netbox, AWX, PAN-OS):

pip install requests

YAML parser (used in helper scripts):

pip install pyyaml

Netbox Python client (for Netbox integration):

pip install pynetbox

Ansible Navigator (modern way to run and inspect playbooks):

pip install ansible-navigator

Or I can install everything in one command:

pip install ansible ansible-lint yamllint paramiko netmiko napalm requests pyyaml pynetbox ansible-navigator

What each package does:

Verifying the Installation

I can verify Ansible is installed and check the version with:

ansible --version

Expected output:

ansible [core 2.17.x]
  config file = None
  configured module search path = ['/home/ansible/.ansible/plugins/modules', ...]
  ansible python module location = /home/ansible/venvs/ansible-network/lib/python3.10/site-packages/ansible
  ansible collection location = /home/ansible/.ansible/collections:/usr/share/ansible/collections
  executable location = /home/ansible/venvs/ansible-network/bin/ansible
  python version = 3.10.12 (main, ...) [GCC 11.4.0]
  jinja version = 3.1.x
  libyaml = True

The key line to confirm: executable location should point into my virtualenv (/home/ansible/venvs/ansible-network/bin/ansible), not /usr/bin/ansible.

Verify the other tools:

ansible-lint --version
yamllint --version
python3 -c "import netmiko; print(netmiko.__version__)"
python3 -c "import napalm; print(napalm.__version__)"
python3 -c "import paramiko; print(paramiko.__version__)"

Installing Ansible Collections

Collections are Ansible’s plugin/module packages. They’re installed separately from pip packages using ansible-galaxy:

Install network vendor collections:

ansible-galaxy collection install cisco.ios
ansible-galaxy collection install cisco.nxos
ansible-galaxy collection install junipernetworks.junos
ansible-galaxy collection install paloaltonetworks.panos

Install utility collections:

ansible-galaxy collection install ansible.netcommon
ansible-galaxy collection install ansible.utils
ansible-galaxy collection install netbox.netbox

Verify installed collections"

ansible-galaxy collection list

Generating requirements.txt

First, I make sure the virtualenv is activated, and then freeze all installed packages and their versions.

pip freeze > requirements.txt

The view the results:

cat requirements.txt

Example output:

ansible==9.8.0
ansible-core==2.17.8
ansible-lint==24.9.2
ansible-navigator==24.8.0
cffi==1.17.1
cryptography==43.0.3
Jinja2==3.1.4
MarkupSafe==2.1.5
napalm==5.0.0
netmiko==4.4.0
nornir==3.4.0
packaging==24.1
paramiko==3.5.0
pynetbox==7.4.0
PyNaCl==1.5.0
pyyaml==6.0.2
requests==2.32.3
resolvelib==1.0.1
setuptools==68.2.0
urllib3==2.2.3
yamllint==1.35.1
...

pip freeze captures every single installed package including dependencies of my dependencies. This guarantees a perfectly reproducible environment.

Two Styles of requirements.txt

There are two common approaches, and both have their place:

Style 1: Pinned versions for Maximum reproducibility

ansible==9.8.0
ansible-lint==24.9.2
netmiko==4.4.0
paramiko==3.5.0

Use this for production environments where I need guaranteed stability. Every engineer gets the exact same versions.

Style 2: Minimum versions for Maximum flexibility

ansible>=9.0.0
ansible-lint>=24.0.0
netmiko>=4.0.0
paramiko>=3.0.0

Use this for open-source or shared projects where I want to allow newer compatible versions. Less strict, but more likely to get the latest bug fixes.

For this lab I use pinned versions from pip freeze for the actual project environment, and keep a separate loose requirements-dev.txt for quick new environment setups where exact versions matter less.

Recreating an Environment

This is the payoff for maintaining requirements.txt. Whether I’m setting up a new VM, onboarding a colleague, or recovering from a broken environment, I can recreate everything in minutes.

Step 1: Clone the project repository:

git clone [email protected]:myusername/ansible-network.git
cd ansible-network

Step 2: Create a fresh virtual environment:

python3 -m venv ~/venvs/ansible-network

Step 3: Activate it:

source ~/venvs/ansible-network/bin/activate

Step 4: Upgrade pip:

pip install --upgrade pip

Step 5: Install all packages from requirements.txt:

pip install -r requirements.txt

Step 6: Reinstall Ansible collections:

ansible-galaxy collection install -r collections/requirements.yml

Step 7: Verify

ansible --version

The -r requirements.txt flag tells pip to read the file and install everything listed in it. The entire environment is rebuilt in one command.

Managing Collections

Just as requirements.txt tracks Python packages, collections/requirements.yml tracks Ansible collections:

mkdir -p ~/projects/ansible-network/collections

Create ~/projects/ansible-network/collections/requirements.yml:

---
collections:
  - name: cisco.ios
    version: ">=8.0.0"
  - name: cisco.nxos
    version: ">=5.0.0"
  - name: junipernetworks.junos
    version: ">=8.0.0"
  - name: paloaltonetworks.panos
    version: ">=2.0.0"
  - name: ansible.netcommon
    version: ">=6.0.0"
  - name: ansible.utils
    version: ">=4.0.0"
  - name: netbox.netbox
    version: ">=3.0.0"

Install from this file:

ansible-galaxy collection install -r collections/requirements.yml

Selecting the Python Interpreter in VS Code

With VS Code connected to my Ubuntu VM via Remote-SSH:

1. Press Ctrl+Shift+P to open the Command Palette
2. Type Python: Select Interpreter and press Enter
3. VS Code scans for available Python environments and shows a list
4. I select the one pointing to my virtualenv:

   Python 3.10.12 ('ansible-network': venv)
   ~/venvs/ansible-network/bin/python3

If VS Code doesn’t detect it automatically, I click Enter interpreter path… and type the full path:

/home/ansible/venvs/ansible-network/bin/python3

Configuring VS Code Settings for the Project

I add a .vscode/settings.json file to my project directory so the interpreter setting is saved with the project and applies automatically when anyone opens it:

mkdir -p ~/projects/ansible-network/.vscode

Create ~/projects/ansible-network/.vscode/settings.json:

{
    "python.defaultInterpreterPath": "/home/ansible/venvs/ansible-network/bin/python3",
    "ansible.python.interpreterPath": "/home/ansible/venvs/ansible-network/bin/python3",
    "ansible.validation.enabled": true,
    "ansible.validation.lint.enabled": true,
    "yaml.schemas": {
        "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/ansible.json#/$defs/playbook": "playbooks/*.yml",
        "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/ansible.json#/$defs/tasks": "roles/*/tasks/*.yml"
    },
    "editor.tabSize": 2,
    "editor.insertSpaces": true,
    "[yaml]": {
        "editor.tabSize": 2,
        "editor.insertSpaces": true,
        "editor.formatOnSave": true
    }
}

• python.defaultInterpreterPath - tells the Python extension which interpreter to use
• ansible.python.interpreterPath - tells the Ansible extension which interpreter to use (must match)
• ansible.validation.enabled - enables real-time playbook validation in the editor
• ansible.validation.lint.enabled - enables ansible-lint integration in VS Code
• yaml.schemas - maps my playbook and task files to the Ansible YAML schema for validation
• editor.tabSize: 2 - YAML best practice is 2-space indentation
• editor.insertSpaces: true - uses spaces, not tabs (tabs in YAML are illegal)
• "[yaml]": { "editor.formatOnSave": true } - auto-formats YAML files on save

Verifying VS Code Sees the Right Environment

After selecting the interpreter, I open a new VS Code terminal (Ctrl+`` ). The virtual environment should activate automatically. I verify:

which ansible
which python3

Expected output:

# /home/ansible/venvs/ansible-network/bin/ansible
# /home/ansible/venvs/ansible-network/bin/python3