Setting Up a Python Development Environment: A Practical Walkthrough

If you've ever tried to start a Python project and found yourself tangled in conflicting package versions, mysterious import errors, or just unsure where to begin, you're not alone. A well-configured development environment saves hours of frustration. This page walks you through a clean, reproducible setup that works on any operating system. You'll learn to isolate dependencies, manage Python versions, and streamline your workflow—so you can focus on writing code instead of fixing configurations.

Quick Answer

The fastest way to set up a professional Python environment is to install pyenv for managing Python versions, create a virtual environment with python -m venv or Poetry for dependency management, and use an editor like VS Code with the Python extension. This combination isolates your projects and prevents version conflicts.

Why Your Python Environment Matters

Python's greatest strength—its vast ecosystem of libraries—is also its biggest headache without proper isolation. Imagine starting Project A which needs Django 3.2 and Project B which requires Django 4.2. Without separate environments, upgrading one breaks the other. Professional developers avoid this by using virtual environments. Additionally, system Python installations (especially on macOS and Linux) are tied to the operating system; modifying them can cause instability.

A solid environment setup also helps you reproduce results. When you share code or deploy to production, having a requirements.txt or pyproject.toml ensures everyone runs the same versions. For deeper understanding of Python's tooling ecosystem, check out https://aminalaee.dev/ for practical insights into modern Python workflows.

Choosing the Right Tools

Here's a comparison of popular environment management tools to help you decide:

Tool	Primary Use Case	Pros	Cons
venv (built-in)	Lightweight virtual environments	No extra installation, simple, reliable	Only manages virtual environments, not Python versions
Poetry	Dependency management + packaging	Lock files, dependency resolution, publish-ready	Learning curve, slower resolver
pipenv	Combined pip + virtualenv	Simple CLI, Pipfile.lock	Slower, fewer updates
conda	Data science, non-Python dependencies	Handles C libraries, large ecosystem	Heavier, different package index

Step-by-Step Setup Guide

1. Install pyenv for Version Management

pyenv lets you install and switch between multiple Python versions without touching system Python.

• On macOS: brew install pyenv
• On Linux: Use the automatic installer: curl https://pyenv.run | bash
• On Windows: Use pyenv-win

Why this matters: You might need Python 3.9 for a legacy project and Python 3.12 for a new one. pyenv keeps them separate. After installation, add eval "$(pyenv init --path)" to your shell profile.

2. Install Your Desired Python Version

List available versions: pyenv install --list or filter by pyenv install --list | grep " 3\.11". Install a version (e.g., 3.11.7):

pyenv install 3.11.7

Set it globally or per project:

pyenv global 3.11.7   # system-wide default
# or, inside a project directory:
pyenv local 3.11.7    # creates .python-version file

3. Create a Virtual Environment

Navigate to your project folder and run:

python -m venv .venv

This creates a .venv directory containing an isolated Python executable and its own pip. Activate it:

• macOS/Linux: source .venv/bin/activate
• Windows (PowerShell): .venv\Scripts\Activate.ps1
• Windows (cmd): .venv\Scripts\activate.bat

Your terminal prompt should now show (.venv). Run which python to confirm it points inside the virtual environment.

4. Install Dependencies

With the virtual environment active, install your project's libraries:

pip install requests flask pytest

Freeze the exact versions into a requirements file:

pip freeze > requirements.txt

This file is your reproducible build blueprint. On another machine or after cloning your repo, run pip install -r requirements.txt.

5. Configure Your Editor

Visual Studio Code with the Python extension automatically detects virtual environments. Open your project folder, press Ctrl+Shift+P, type "Python: Select Interpreter", and choose the one inside .venv. This ensures linting, IntelliSense, and debugging all use the correct environment.

Common Pitfalls and Fixes

Problem	Likely Cause	Solution
pip: command not found	Python not installed or PATH misconfigured	Run python -m ensurepip --upgrade or reinstall Python
Package installs globally instead of in venv	Virtual environment not activated	Run source .venv/bin/activate (or Windows equivalent) before pip install
pyenv: command not found	Shell configuration not reloaded	Restart your terminal or run exec "$SHELL"
VS Code doesn't recognize the environment	Interpreter not selected	Use command palette to select the Python interpreter from .venv
Different project requires different Python version	Using one global Python	Use pyenv local 3.10.0 inside that project's directory

Best Practices from Experienced Developers

Beyond the basic setup, seasoned Python developers follow these habits to keep environments clean and productive:

• Commit requirements.txt but not .venv. This balances reproducibility with avoiding bloat in your repository.
• Use .python-version for teams. pyenv reads this file automatically, ensuring all team members use the same Python version.
• Update dependencies intentionally. Run pip list --outdated periodically, then test upgrades one at a time rather than bulk-updating.
• Keep global pip clean. Install only tools like black, ruff, or poetry globally. Everything else lives in virtual environments.
• Name your environments consistently. Using .venv (with the dot) is a community convention that hides the directory and signals it's auto-generated.

Frequently Asked Questions

What's the difference between pyenv and virtualenv?

pyenv manages Python versions (e.g., switching between Python 3.9 and 3.12), while virtualenv and venv create isolated environments using a single Python version. They work together: pyenv picks the version, venv creates the isolated space.

Should I use venv or virtualenv?

Use venv if you're on Python 3.3 or later—it's built-in and sufficient for most cases. virtualenv offers some advanced features like creating environments for older Python versions, but venv covers the vast majority of needs.

How do I delete a virtual environment?

Simply delete the directory: rm -rf .venv (macOS/Linux) or rmdir /s .venv (Windows). There's no unregister command. If you're using poetry or pipenv, use their specific removal commands (poetry env remove, pipenv --rm).

Can I use Docker instead of virtual environments?

Yes, Docker provides stronger isolation by containerizing the entire OS environment. However, for local development, virtual environments are lighter and faster. Many developers use virtual environments for daily work and Docker for production deployment.

Why does pip freeze show packages I didn't install?

Those are dependencies of dependencies (transitive dependencies). pip freeze lists all installed packages, not just the ones you explicitly listed. Use pip list --format=freeze to see only top-level packages, or use Poetry which separates direct and transitive dependencies in the lock file.

Setting up a proper Python environment takes fifteen minutes, but the time saved debugging version conflicts and import errors repays that investment many times over. Start with pyenv, venv, and a clean requirements.txt—you can always add more sophisticated tools later as your projects grow in complexity. The key is to build the habit of always working inside an isolated environment from the very first line of code.