Set Up a Python AI Environment

You've built solid Python foundations over the last 25 lessons, but now you're about to take on your first real AI project. You install TensorFlow, then PyTorch, then a LangChain template, and suddenly pip is fighting with itself, your GPU is invisible to your code, and you can't tell which package version your experiments actually ran on. That mess isn't a sign you're bad at coding — it's a sign you skipped the setup phase. In this lesson, you'll learn how to set up a Python AI development environment that is reproducible, isolated, and fast enough to prototype and productionize like a professional applied AI engineer.

The Problem This Lesson Solves

Most AI tutorials skip straight to the model code, but that's like teaching someone to drive by handing them keys to a car with no oil. Here's the real pain you've likely already felt:

• Dependency hell: pip install torch works on your laptop, then breaks your teammate's setup because they have a different CUDA version.
• Silent version drift: You ran an experiment last week that gave you 94% accuracy, but now import transformers pulls a newer tokenizer that changes your results — and you have no idea why.
• Environment pollution: You install packages globally, and suddenly your data-science project and your Django web app are fighting over the same NumPy version.
• GPU misconfiguration: Your code runs fine on CPU but grotesquely slow, and you only discover later that CUDA wasn't installed properly.

These problems don't just waste hours — they undermine the trust you place in your own results. A proper AI development environment isn't a luxury; it's a foundational practice that lets you focus on your model, not your package manager.

Core Concept / Mental Model

Think of your AI development environment as a clean lab bench for every experiment. Each project gets its own isolated workspace (a virtual environment), a dependency manifest (a file that says exactly what's on the bench), and a reproducible launch sequence (how you step into that workspace).

The mental model breaks down into three layers:

1. The base Python interpreter — the raw runtime that executes your code.
2. The virtual environment — a per-project copy of that runtime with its own site-packages folder, so package versions don't leak between projects.
3. The orchestration layer — tools like uv, poetry, or conda that manage the virtual environment, dependencies, and lock files for you.

Pro tip: AI projects are especially sensitive to isolation because deep-learning frameworks like PyTorch and TensorFlow have complex binary dependencies (CUDA, cuDNN) that can't share a global namespace without conflicts.

Once you internalize this three-layer model, every setup step becomes predictable: create a lockfile → create an environment from it → install dependencies → verify the GPU works → run your experiment.

How It Works Step by Step

Here is the recommended, battle-tested sequence for setting up a Python AI development environment:

1. Choose Your Package Manager

Modern AI development has moved beyond bare pip + venv. You have three strong contenders:

• pip + venv — Python's built-in tools, simple and universal, but slow and lockfiles (requirements.txt) are often incomplete.
• uv — a fast, Rust-based drop-in replacement for pip/venv that generates a proper uv.lock file. It's the current darling of the Python community for a reason.
• conda / miniconda — best for managing non-Python binary dependencies like CUDA. If you're on Windows or need strict GPU control, conda is a safe choice.

2. Create a Project-First Structure

Never install AI packages globally. Create a dedicated project folder with a pyproject.toml (or requirements.txt) at its root. This manifest becomes your single source of truth.

3. Generate a Lockfile

A lockfile pins exact versions of every package — including transitive dependencies — so your environment is byte-for-byte reproducible. uv.lock does this for uv, and poetry.lock does it for Poetry.

4. Create and Activate the Virtual Environment

The tool you chose creates a .venv folder inside your project. Activation is just a shell command that points your python to that folder's interpreter.

5. Install AI Frameworks Incrementally

Install your core frameworks (PyTorch or TensorFlow) first, then add higher-level libraries like transformers or langchain. This order helps you isolate version conflicts.

6. Verify Everything with a Hello-World Script

Run a tiny script that imports your framework and checks for GPU availability. If it fails, you know it's your environment — not your model code.

Pro tip: Always document your setup steps in a README.md. Your future self will thank you when you come back to a project six months later.

Hands-On Walkthrough

Let's walk through the entire process using uv — the fastest and most modern approach. You'll build a minimal AI environment with PyTorch and the Hugging Face Transformers library.

First, install uv on macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows (PowerShell), use:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Now create your project structure and virtual environment:

mkdir my_ai_project && cd my_ai_project
uv init

# This creates pyproject.toml and .venv automatically.
# Add your AI dependencies (this command also generates uv.lock)
uv add torch transformers

When the command finishes, you'll see a uv.lock file. Let's verify the environment works:

# Activate the virtual environment (on Linux/macOS)
source .venv/bin/activate

# On Windows: .venv\Scripts\activate

python --version
# Should output Python 3.12.x (or whatever you specified)

python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
# Expected output (on a GPU machine): CUDA available: True
# On a CPU-only machine: CUDA available: False

Now write a tiny transformer script to confirm everything is wired up. Create check_env.py:

from transformers import pipeline

classifier = pipeline("sentiment-analysis", model="distilbert-base-uncased-finetuned-sst-2-english")
result = classifier("I'm so happy to have a clean AI environment!")
print(result)
# Expected output: [{'label': 'POSITIVE', 'score': 0.9998...}]

Run it after you've activated the environment:

python check_env.py

You should see a positive sentiment prediction, proving that transformers, torch, and the model download all work. If this runs, your environment is production-ready for AI development.

Pro tip: Always run a version check and GPU check as part of your CI pipeline. It's the single best defense against silent environment rot.

Compare Options / When to Choose What

The table below compares the three most common ways to set up a Python AI development environment, so you can pick the right tool for your context.

When to choose what:

• Start with uv unless you have a specific reason not to. It's fast, reproducible, and becoming the industry standard.
• Use conda if you're on Windows and need to install CUDA drivers as a package, or if your team already standardizes on conda.
• Fall back to pip + venv when you're in a constrained environment (e.g., a university server with no admin rights) and can't install third-party tools.

Troubleshooting & Edge Cases

You'll hit these issues at some point; here's how to diagnose them fast.

ImportError: No module named 'torch'

You're either not in the activated virtual environment, or you installed torch globally by accident. Fix: which python, source .venv/bin/activate, then uv add torch.

torch.cuda.is_available() returns False even with an NVIDIA GPU

This is the most common GPU issue. Check your CUDA driver version:

nvidia-smi
# If it errors, you don't have NVIDIA drivers installed.

Then reinstall PyTorch with the matching CUDA version, e.g.:

uv pip install torch --index-url https://download.pytorch.org/whl/cu121

Version mismatch between transformers and torch

Sometimes a new transformers version requires a newer torch, causing cryptic errors. Fix: run uv lock --upgrade-package torch to update both in sync.

uv add is slow or hangs

It may be a network issue or a huge dependency tree. Try uv add --no-cache to skip the cache, or set a custom index via UV_DEFAULT_INDEX environment variable.

What You Learned & What's Next

You've now built a reproducible Python AI environment using uv, installed deep learning frameworks, and verified both CPU and GPU functionality. You understand the three-layer mental model — base interpreter, virtual environment, orchestration tool — and you know how to choose between pip/venv, uv, and conda based on your project's needs.

You've also practiced the essential first step of any applied AI workflow: isolate first, then code. This habit will save you countless debugging hours.

Next up: In the next lesson, we'll take this clean environment and build your first real AI application — calling a model to generate structured output. You'll see why a solid environment setup is the foundation for all that exciting work to come.

Quick recap of what you learned:

• The importance of isolating AI dependencies per project.
• How to use uv to create a lockfile-based environment in seconds.
• How to verify GPU availability with a one-liner.
• How to compare tools and pick the right one for your team.

Now go clean up that global site-packages mess you've been ignoring — and build something great.