Set Up Your Python Dev Environment

Setting up a Python development environment sounds like a chore you can postpone — until you've spent an hour fighting virtual environments, another chasing a broken pip install, and a third discovering that your automation script works on your laptop but nowhere else. That pain is real and it multiplies in DevOps, where every tool you build must be portable, reproducible, and safe to run against live infrastructure. In this lesson, you'll learn a proven setup that makes every Python project predictable from day one — and you'll practice it hands-on so you can stop guessing and start shipping automation you actually trust.

The problem this lesson solves

Every Python developer has hit these walls, and they're especially nasty in DevOps automation:

• Dependency hell — you pip install a package for one script, and suddenly another script breaks because the version changed underneath you.
• Global pollution — you install tools system-wide, and soon you have conflicting versions of libraries like requests or boto3 fighting each other.
• Non-reproducible environments — your automation works on your machine, but your teammate's requirements.txt doesn't match what you tested, so the same script behaves differently in production.

In DevOps, these problems are amplified. Your Python scripts might run on a CI server, a cron job, or a container. If the environment isn't locked down, your automation is a ticking time bomb — it will fail at the worst possible moment, often overnight, and the error message will be a cryptic traceback about a missing module.

Without a solid setup, you're not just wasting time — you're shipping risk. You'll deploy code that worked in your editor but fails in the pipeline because of a subtle version mismatch. The fix isn't to "just be more careful." It's to adopt a structured approach that makes correctness the default.

Core concept / mental model

Think of your Python dev environment as a clean workbench with labeled drawers. The workbench is your project directory. Each drawer is an isolated space for one project's dependencies — no mixing, no confusion. You open the drawer by activating it, you close it when you're done, and every drawer is built from the same blueprint so anyone can recreate it.

The three pillars: venv, pip, and requirements

• Virtual environment (venv) — a self-contained directory that holds a specific Python interpreter and its own installed packages. It's like a clone of Python that lives inside your project folder.
• pip — the package installer. It's the tool that fetches libraries from PyPI and places them into your active environment.
• requirements file — a plain text file where you list every dependency with a pinned version (e.g., boto3==1.34.0). This is your blueprint, letting anyone recreate the exact same environment.

Why this matters for DevOps

When you write automation for DevOps, you're often touching infrastructure: AWS via boto3, Azure via the Azure SDK, or Kubernetes via kubernetes client. Each tool has heavy dependencies and frequent updates. If you don't isolate them, you're one pip install --upgrade away from breaking a script that your whole team relies on.

How it works step by step

Here's the mental pipeline you'll follow for every project:

1. Create a project directory — keep each automation script or tool in its own folder.
2. Create a virtual environment inside that directory with python -m venv venv.
3. Activate the environment — on Linux/macOS: source venv/bin/activate; on Windows: venv\Scripts\activate. Your terminal prompt will change to show (venv).
4. Install dependencies with pip install <package> while the environment is active. Pin versions if you want reproducibility.
5. Freeze your dependencies into a requirements.txt file using pip freeze > requirements.txt so the exact versions are saved.
6. Deactivate when you're done with deactivate — this closes the drawer and keeps your system Python clean.

Why this sequence works

• Each step builds on the previous one: you can't install packages into an environment that doesn't exist, and you can't pin versions until you've chosen them.
• The virtual environment keeps everything local, so your global Python stays untouched.
• The requirements.txt file is the bridge to reproducibility — a colleague (or a future you) can run pip install -r requirements.txt and instantly get the same setup.

Hands-on walkthrough

Let's build a real DevOps-oriented environment. We'll create a project for an AWS automation script using boto3 (the official AWS SDK for Python).

Step 1: Check your Python version

First, make sure you have Python 3.10 or newer — this track uses current syntax and features.

python --version
# Output: Python 3.12.3 (or similar)

Step 2: Create a project directory and virtual environment

mkdir aws-automation
cd aws-automation
python -m venv venv

The venv folder now holds an isolated Python installation. Your global Python isn't affected.

Step 3: Activate the environment

# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

Your prompt should now show (venv). That confirms you're inside the isolated workspace.

Step 4: Install a package and pin its version

pip install boto3==1.34.0

Now let's quickly verify it's usable by writing a tiny script that lists your S3 buckets (if you have AWS credentials set up).

Step 5: Write and run a small automation script

# list_s3.py
import boto3

s3 = boto3.client('s3')
buckets = s3.list_buckets()

print('Your S3 buckets:')
for b in buckets['Buckets']:
    print(f" - {b['Name']}")

Run it:

python list_s3.py
# Output (example):
# Your S3 buckets:
#  - my-devops-storage

Step 6: Save your environment's exact state

pip freeze > requirements.txt
cat requirements.txt

The output looks something like:

boto3==1.34.0
botocore==1.34.0
s3transfer==0.10.0
urllib3==2.0.0

Now anyone — or any CI server — can run pip install -r requirements.txt and get the identical environment.

Pro tip: Always pin versions in requirements.txt. Using pip freeze > requirements.txt captures exact versions, which is what you need for production-grade reproducibility.

Compare options / when to choose what

The virtual environment approach is the standard, but other tools exist. Here's a quick comparison to help you choose:

For most DevOps automation scripts, venv + requirements.txt is the sweet spot: it's built into Python, requires no extra tooling, and is universally understood. If you start publishing packages to PyPI or need advanced dependency graphs, consider Poetry later.

When to reach for each

• Use venv for 95% of your automation scripts.
• Use conda if your automation depends on C/C++ libraries like numpy that pip struggles to install cleanly.
• Use poetry if you're building a multi-module tool that you'll distribute to other teams.
• Skip pipenv unless you already love it — its benefits are marginal for short automation scripts.

Troubleshooting & edge cases

Even with a clean setup, things go wrong. Here are the most common issues and how to fix them.

pip: command not found

If you can't find pip, your environment isn't activated or pip isn't installed. For modern Python, use python -m pip instead of bare pip.

python -m pip install boto3

ModuleNotFoundError: No module named 'boto3'

This usually means the module is installed in a different environment than the one running the script. Check:

which python
# Should point inside your venv, like ~/myproject/venv/bin/python

If it doesn't, activate the environment again.

pip freeze includes packages you didn't plan

Sometimes pip freeze lists transitive dependencies — that's normal. But if a pip upgrade pulled a new version of a sub-dependency that breaks something, pin it explicitly. For example:

urllib3<2

in requirements.txt to avoid breaking code that relied on an older API.

Activating the environment does nothing

On Windows, you might need to run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser to allow script execution. On Linux/macOS, make sure you use source, not just typing the path.

System Python vs. virtual environment

If your system Python is intentionally strict (some Linux distros disable pip install globally), virtual environments solve that — they give you full control without touching system packages.

Pro tip: Always run python -m venv venv from inside the project folder. This keeps the environment's path short and avoids accidental pollution of other projects.

What you learned & what's next

You now understand the core idea behind setting up a Python dev environment: isolation through virtual environments, dependency management with pip, and reproducibility via requirements.txt. You proved it with a real exercise that installed boto3 and ran an AWS automation script. You also know how to compare tools like venv vs. Poetry and how to troubleshoot the most common hiccups.

You've met the lesson's objectives — you can explain why isolation matters and you can complete the practical setup from scratch.

Now that your environment is solid, you're ready for the next step in the track: [Next lesson topic] where you'll use that environment to write your first actual DevOps automation script. A clean environment is the foundation — now you get to build on it.