If you have ever run pip install for an AI project and ended up with a broken setup, conflicting package versions, or a mysterious “CUDA not available” error, you are not alone. A messy Python environment is the number one reason beginners get stuck before writing a single line of model code.
The good news is a proper setup takes about 20 minutes, and you only need to learn it once.
In this guide, you will build a clean, reproducible Python environment for AI development that works on Windows, macOS, and Linux.
What you will need?
- A computer with at least 8 GB of RAM (a 16 GB or more is better).
- Around 10 GB of free disk space.
- An internet connection.
- Optional but worth to have an NVIDIA GPU for faster model training.
No prior Python environment knowledge is required.
Why a dedicated Python environment matters?
AI libraries such as PyTorch, TensorFlow, Transformers, and scikit-learn depend on specific versions of NumPy, CUDA, and other packages. If you install everything into your system Python, one project can break another. A virtual environment solves this by giving each project its own isolated set of packages. Think of it as a separate toolbox per project, so a wrench from one never goes missing from another.
Step 1: Install a supported Python version.
For AI work, pick a stable, widely supported Python release. Python 3.12 is a safe choice today, and 3.13 works with most major libraries. Before choosing a newer version, check that PyTorch or TensorFlow supports it, because new Python releases often take a while to get full library support.
Check whether Python is already installed:
python --versionOn macOS or Linux you may need python3 --version.
If you do not have a suitable version, you can let the tool in Step 2 install it for you, which is the easiest route.
Step 2: Install uv (the fast way to manage Python).
uv is a modern, very fast Python package and project manager. It can install Python versions, create virtual environments, and install packages, replacing several older tools at once.
Install it on macOS or Linux:
curl -LsSf https://astral.sh/uv/install.sh | shInstall it on Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Restart your terminal, then confirm it works:
uv --versionPrefer the classic approach? Everything in this guide also works with Python’s built-in venv and pip. Alternatives are listed in the comparison table below.
Step 3: Create a project folder and virtual environment.
Create a folder for your project and move into it:
mkdir my-ai-project
cd my-ai-projectCreate a virtual environment with a specific Python version:
uv venv --python 3.12This creates a hidden .venv folder inside your project. Activate it:
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1Your terminal prompt should now show (.venv), which means the environment is active. Every package you install from now on stays inside this project.
Step 4: Install core AI and data science libraries.
With the environment active, install the essentials:
uv pip install numpy pandas matplotlib scikit-learn jupyterlabHere is what each one does:
| Library | What it is used for? |
|---|---|
| NumPy | Fast numerical arrays and math. |
| pandas | Loading and cleaning tabular data. |
| Matplotlib | Charts and visualizations. |
| scikit-learn | Classic machine learning algorithms. |
| JupyterLab | Interactive notebooks for experiments. |
Step 5: Install a deep learning framework.
Most modern AI work uses PyTorch, so we will start there. The correct install command depends on your operating system and whether you have an NVIDIA GPU. The most reliable way to get it right is to use the official selector on the PyTorch website (pytorch.org, “Get Started” section), which generates the exact command for your setup.
For a basic install, the command typically looks like this:
uv pip install torch torchvision torchaudioIf you want to work with pretrained language models and generative AI, also install the Hugging Face libraries:
uv pip install transformers datasets acceleratePrefer TensorFlow or Keras? Install it the same way with uv pip install tensorflow, and check its documentation for the Python versions and GPU requirements it currently supports. Avoid installing both frameworks in the same environment unless you really need to, since they can pull in conflicting dependencies.
Step 6: Set up GPU support (optional but powerful).
Training neural networks on a CPU works for learning, but a GPU can make training dramatically faster.
If you have an NVIDIA GPU:
- Install the latest NVIDIA driver for your card.
- Install the PyTorch build that matches your setup, using the selector on pytorch.org.
- You usually do not need to install the full CUDA Toolkit separately, because PyTorch’s official builds bundle the CUDA runtime they need.
If you use a Mac with Apple Silicon (M-series): PyTorch supports GPU acceleration through the mps backend. No extra installation is needed beyond PyTorch itself.
If you have no GPU: Do not worry. You can learn and prototype on CPU, and use free or low-cost cloud notebooks when you need more power.
Step 7: Verify your installation.
This is the step most tutorials skip, and it saves hours of frustration. Create a file called check_env.py:
import sys
import numpy as np
import pandas as pd
import torch
print("Python:", sys.version.split()[0])
print("NumPy:", np.__version__)
print("pandas:", pd.__version__)
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
print("Apple MPS available:", torch.backends.mps.is_available())
x = torch.rand(3, 3)
print("Random tensor:\n", x)Run it:
python check_env.pyIf you see version numbers and a random tensor printed without errors, your environment works. If you have an NVIDIA GPU and CUDA available shows False, update your GPU driver and reinstall PyTorch using the official selector command.
Step 8: Use jupyter for experiments.
JupyterLab lets you run code in small cells and see results instantly, which is ideal for exploring data and testing models.
Start it from inside your activated environment:
jupyter labYour browser will open. Create a new notebook and make sure it uses your project’s .venv kernel. If it does not appear in the kernel list, register it:
uv pip install ipykernel
python -m ipykernel install --user --name my-ai-projectStep 9: Choose a good code editor
You can write AI code in any editor, but two options stand out:
- Visual Studio Code with the official Python and Jupyter extensions. It detects your
.venvautomatically and handles notebooks well. - PyCharm, a full Python IDE with strong debugging and project tools.
In VS Code, press Ctrl+Shift+P (or Cmd+Shift+P on Mac), choose Python: Select Interpreter, and pick the one inside your .venv folder.
Step 10: Make your environment reproducible.
A setup that only works on your machine is a ticking time bomb. Save your dependencies so you or a teammate can rebuild the same environment later.
Export your installed packages:
uv pip freeze > requirements.txtRecreate the environment on another machine:
uv venv --python 3.12
source .venv/bin/activate
uv pip install -r requirements.txtFor larger projects, consider managing dependencies with a pyproject.toml file and uv add, which records packages automatically and keeps a lock file for exact versions.
Also add a .gitignore file so you never commit your environment or secrets:
.venv/
__pycache__/
.env
*.ipynb_checkpointsTool comparison: venv vs. uv vs. Conda
| Feature | venv + pip | uv | Conda |
|---|---|---|---|
| Comes with Python | Yes | No (one-line install) | No |
| Speed | Moderate | Very fast | Slower |
| Installs Python versions | No | Yes | Yes |
| Handles non-Python packages | No | No | Yes |
| Best for | Simple projects | Most AI developers | Scientific stacks with complex native dependencies |
Our recommendation: start with uv for speed and simplicity. Choose Conda if you rely on packages with heavy non-Python dependencies.
Common problems and quick fixes.
“python is not recognized” or “command not found” Python is not on your PATH. Reinstall it and enable the PATH option on Windows, or use python3 on macOS and Linux.
PowerShell blocks the activation script Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, then try activating again.
Package conflicts or strange import errors Delete the .venv folder, recreate it, and reinstall from your requirements.txt. A fresh environment fixes most problems faster than debugging.
Jupyter uses the wrong Python Register your environment as a kernel (see Step 8) and select it inside the notebook.
“CUDA out of memory” Reduce your batch size, use a smaller model, or enable mixed precision training.
Best practices for AI developers.
- One environment per project. Never install AI libraries into your system Python.
- Pin your versions once a project works, so updates do not silently break it.
- Keep secrets out of code. Store API keys in a
.envfile or environment variables, and never commit them to Git. - Verify before you build. Run a quick environment check whenever you set up a new machine.
- Prefer a fresh rebuild over repair. Environments are cheap to recreate.
Frequently Asked Questions (FAQ).
Which Python version is best for AI development? Choose a stable release that your main libraries explicitly support. Python 3.12 is a reliable choice today. Always check the PyTorch or TensorFlow install page before upgrading to the newest version.
Do I need a GPU to learn AI? No. You can learn the fundamentals, build small models, and run many pretrained models on a CPU. A GPU becomes important when training larger models.
Should I use Anaconda or a virtual environment? Both work. Virtual environments with uv or pip are lighter and faster for most projects. Conda is useful when you need complex non-Python dependencies.
Do I need to install CUDA separately? Usually not for PyTorch, since official builds include the CUDA runtime. You do need an up-to-date NVIDIA driver.
Can I use Windows for AI development? Yes. The steps in this guide work on Windows, macOS, and Linux. Windows users who want a Linux-like workflow can also use WSL2.
How do I share my environment with a teammate? Share your requirements.txt (or pyproject.toml and lock file) through Git, and they can rebuild the same environment with a single command.
Conclusion.
A clean Python environment is the foundation of every successful AI project. With uv, a virtual environment, the right libraries, and a quick verification script, you now have a setup that is fast, isolated, and reproducible.
Next, try training a small model on a sample dataset, or load a pretrained model with the Hugging Face Transformers library. Your environment is ready.
Found this guide helpful? Share it with a friend who is starting their AI journey.
