Setting Up Your AI Dev Environment — The Right Way

This post is the environment setup I wish someone had given me before I started. If you're following the AI Fieldnotes series, this is Post 2 — we're building the foundation before anything else. By the end, you'll have a clean, reproducible Python environment ready for every project in this series.

What You'll Set Up

• Python 3.11+ installed correctly

• VS Code as your editor

• uv — the modern Python package manager that replaces pip, venv, and virtualenv in one tool

• .env files for API keys

• python-dotenv to load them safely

• A quick smoke test to confirm everything works

1. Install Python 3.11+

AI libraries like LangChain, LangGraph, and the OpenAI SDK actively target Python 3.10–3.12. Don't use 3.9 or below — you'll hit dependency walls fast.

macOS:

# Check what you have first
python3 --version

# Install with Homebrew
brew install python@3.11

Ubuntu / Debian:

sudo apt update && sudo apt install python3.11

Windows:

Download the installer from python.org. During install, check "Add python.exe to PATH" — this saves a lot of pain later.

Verify after install:

python3 --version
# Python 3.11.x

2. Install VS Code

VS Code is the standard editor for Python AI work. Download it at code.visualstudio.com.

When you open a Python file, VS Code will automatically suggest the Python extension — accept it. That's genuinely all you need to get started. The editor handles the rest through its built-in language support.

3. Install uv

uv is a Rust-based Python package manager. It replaces pip, venv, and virtualenv entirely. When you run uv add, it creates and manages a virtual environment for you automatically — you never think about it.

It's also 10–100× faster than pip. Once you use it, going back feels painful.

macOS / Linux:

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

Windows (PowerShell):

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

Restart your terminal, then verify:

uv --version
# uv 0.x.x

4. Create Your Project

# Create and enter your project folder
mkdir my-ai-project && cd my-ai-project

# Initialise a uv project
uv init

uv init creates a pyproject.toml and a .python-version file. That's your project. No manual venv creation, no activation step — uv handles the isolated environment behind the scenes every time you run uv add or uv run.

Open it in VS Code:

code .

5. Install the Core Libraries

Use uv add instead of pip install. It resolves dependencies, pins them in a uv.lock file, and installs into the project's managed environment automatically.

uv add \
  langchain \
  langchain-openai \
  langchain-anthropic \
  langchain-community \
  openai \
  anthropic \
  python-dotenv \
  tiktoken \
  faiss-cpu

To reproduce this environment on another machine or server:

uv sync

That reads uv.lock and installs exact versions. Commit uv.lock to Git — it's what makes your environment reproducible. Do not commit .venv/ (add it to .gitignore).

Coming from pip? The mental mapping is simple: pip install X → uv add X, and pip install -r requirements.txt → uv sync.

6. Manage API Keys with dotenv

This is where most beginners get burned. You need API keys for OpenAI, Anthropic, or whichever provider you're using — and those keys must never appear in your code.

The pattern: store keys in a .env file, load them at runtime with python-dotenv, and keep .env out of Git forever.

Create your .env file in the project root:

OPENAI_API_KEY=sk-...your-key-here...
ANTHROPIC_API_KEY=sk-ant-...your-key-here...
LANGCHAIN_API_KEY=ls__...your-key-here...
LANGCHAIN_TRACING_V2=true

Load them in your Python code:

from dotenv import load_dotenv
import os

load_dotenv()  # reads .env and populates os.environ

openai_key = os.getenv("OPENAI_API_KEY")
print(f"Key loaded: {openai_key[:8]}...")  # never print the full key

Call load_dotenv() at the very top of your entry-point file, before any LLM imports. It's silent if .env doesn't exist — it won't crash, but your keys won't load either.

Why not just export them in the terminal? Environment variables set in a shell session disappear when the session ends. .env + dotenv gives you reproducibility across machines and teammates.

Add these to your .gitignore now, before your first commit:

.venv/
__pycache__/
.env

7. Smoke Test — Confirm Everything Works

Create a file called test_setup.py:

from dotenv import load_dotenv
import os

load_dotenv()

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

# Confirm key is loaded
api_key = os.getenv("OPENAI_API_KEY")
assert api_key, "OPENAI_API_KEY not found — check your .env file"
print(f"✓ API key loaded ({api_key[:8]}...)")

# Make a real LLM call
llm = ChatOpenAI(model="gpt-4o-mini")
response = llm.invoke([HumanMessage(content="Say 'setup complete' and nothing else.")])
print(f"✓ LLM response: {response.content}")

Run it:

uv run test_setup.py

uv run executes the script inside the managed environment — no manual activation needed. If you see two green checkmarks, you're good. If you see AuthenticationError, your key isn't loading — double-check the .env filename and that it's in the project root.

Common Mistakes

"It works on my machine but not on the server." Almost always a missing .env file, or a key that was set as a shell variable but not written to .env. On a server, always load from .env explicitly.

Forgetting uv sync after cloning. When you clone a repo that uses uv, run uv sync before anything else. It reads uv.lock and recreates the exact environment.

Committing .env to Git. Add it to .gitignore before your first commit. GitHub's secret scanning will flag it, but by then the key may already be exposed in history.

Project Structure Going Forward

my-ai-project/
├── .venv/              # Never committed — managed by uv
├── .env                # Never committed
├── .gitignore
├── pyproject.toml      # Your project config
├── uv.lock             # Commit this — it's your lockfile
├── main.py
└── src/
    ├── chains/
    ├── tools/
    └── memory/

What's Next

With your environment set up, we're ready to build something real. In Post 3, we'll write your first LangChain app — a Gmail support-triage agent that classifies incoming tickets with a single LLM call. You'll see exactly how load_dotenv(), a chain, and an output parser connect into a working tool.

If you're stuck on any part of setup, find me on LinkedIn — I read every message.

Khair Ahammed — AI Engineer building production-ready agents