Python Environment Setup: pyenv, venv, conda, and uv

Introduction

A proper Python environment setup prevents the classic “it works on my machine” problem. This guide covers the full stack: installing Python, managing multiple versions with pyenv, isolating project dependencies with virtual environments, and using modern tools like uv for speed.

Installing Python

Linux (Ubuntu/Debian)

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

# Verify
python3 --version
pip3 --version

Important: Never overwrite the system Python (/usr/bin/python3). Use python3 explicitly or install a separate version via pyenv.

macOS

# Using Homebrew (recommended)
brew install python

# Or install pyenv first (see below)

Windows

Download from python.org and check “Add Python to PATH” during installation.

Python Version Management with pyenv

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

Install pyenv

# Linux/macOS
curl https://pyenv.run | bash

# Add to ~/.bashrc or ~/.zshrc
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

source ~/.bashrc

Common pyenv Commands

# List available Python versions
pyenv install --list | grep "3\."

# Install a specific version
pyenv install 3.12.0
pyenv install 3.11.5

# List installed versions
pyenv versions

# Set global default
pyenv global 3.12.0

# Set version for current directory (creates .python-version file)
pyenv local 3.11.5

# Set version for current shell session
pyenv shell 3.10.0

# Verify
python --version

Virtual Environments

Virtual environments isolate project dependencies so different projects can use different package versions.

venv (Built-in, Recommended)

# Create a virtual environment
python3 -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Verify you're in the venv
which python    # should show .venv/bin/python
pip list        # shows only packages in this venv

# Install packages
pip install requests pandas numpy

# Deactivate
deactivate

Always add .venv to .gitignore

echo ".venv/" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore

virtualenv (Third-party, more features)

pip install virtualenv

# Create with specific Python version
virtualenv -p python3.11 .venv

# Create with system packages accessible
virtualenv --system-site-packages .venv

Conda: For Data Science

Conda manages both Python versions and packages, and handles non-Python dependencies (C libraries, CUDA, etc.) better than pip.

Install Miniconda (Lightweight)

# Download and install
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# Or use Homebrew on macOS
brew install --cask miniconda

Essential Conda Commands

# Create environment
conda create -n myproject python=3.12

# Activate
conda activate myproject

# Deactivate
conda deactivate

# List environments
conda env list

# Install packages
conda install numpy pandas scikit-learn
conda install -c conda-forge some-package  # from conda-forge channel

# Install pip packages in conda env
pip install some-package

# Export environment
conda env export > environment.yml

# Recreate from file
conda env create -f environment.yml

# Remove environment
conda remove -n myproject --all

# Update conda itself
conda update conda

When to Use conda vs pip+venv

Scenario	Use
Data science, ML, scientific computing	conda
Web development, general Python	pip + venv
Need CUDA, MKL, or C library dependencies	conda
Deploying to production	pip + venv (lighter)
Working with Jupyter notebooks	conda

uv: The Modern Fast Alternative

uv is a Rust-based Python package manager that’s 10-100x faster than pip. It’s becoming the standard for new projects.

# Install uv
pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a project with virtual environment
uv init myproject
cd myproject

# Create venv
uv venv

# Install packages (much faster than pip)
uv pip install requests pandas numpy

# Install from requirements.txt
uv pip install -r requirements.txt

# Sync dependencies from pyproject.toml
uv sync

# Run a command in the venv
uv run python script.py
uv run pytest

Project Structure Best Practice

myproject/
├── .venv/              # virtual environment (gitignored)
├── .python-version     # pyenv version file
├── pyproject.toml      # project metadata and dependencies
├── requirements.txt    # pinned dependencies for deployment
├── requirements-dev.txt # development dependencies
├── src/
│   └── myproject/
│       └── __init__.py
└── tests/
    └── test_main.py

pyproject.toml (Modern Standard)

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.1.0",
    "mypy>=1.0",
]

[tool.ruff]
line-length = 88
select = ["E", "F", "I"]

[tool.mypy]
python_version = "3.11"
strict = true

VS Code Configuration

// .vscode/settings.json
{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "charliermarsh.ruff"
    }
}

Select the interpreter via Command Palette (Ctrl+Shift+P) → “Python: Select Interpreter” → choose .venv/bin/python.

Linting and Formatting

# ruff: fast linter + formatter (replaces flake8, black, isort)
pip install ruff

# Check for issues
ruff check .

# Fix automatically
ruff check --fix .

# Format code
ruff format .

# mypy: static type checking
pip install mypy
mypy src/

# pytest: testing
pip install pytest
pytest tests/

Common Issues and Fixes

Wrong Python version being used

# Check which python is active
which python
python --version

# If wrong, activate the right venv or use pyenv local
pyenv local 3.12.0
source .venv/bin/activate

pip installs to wrong location

# Always activate venv first
source .venv/bin/activate
pip install package  # now installs to .venv

# Or use python -m pip to be explicit
python -m pip install package

Dependency conflicts

# Check for conflicts
pip check

# Start fresh
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt