# Installation
*(Last updated: 23 July 2026)*

This guide provides instructions for setting up a local Python environment with PyTorch installed. The installation process is streamlined using [uv](https://docs.astral.sh/uv/), which simplifies the management of Python versions, virtual environments, and dependencies. The instructions cover the installation of Python, the setup of a project folder, and the addition of various Python libraries, including PyTorch and TorchVision.


## Step 1: Install uv

Install uv using the package manager for your operating system.

- MacOS (using [Homebrew](https://brew.sh/))
  ```
  brew install uv
  ```

- Windows (using PowerShell)
  ```
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

- See the [uv documentation](https://docs.astral.sh/uv/getting-started/installation/) for other installation methods.

After the installation, close the terminal to apply the changes. If you are working in Visual Studio Code, restart the editor as well. Then, run the command `uv --version` in a new terminal to verify that uv is installed correctly.


## Step 2: Install Python

If Python is already installed on your system, uv will detect and use it without configuration. The [`uv python list`](https://docs.astral.sh/uv/concepts/python-versions/#viewing-available-python-versions) command allows you to see installed and available Python versions.

```
uv python list
```

You can install Python using the [`uv python install`](https://docs.astral.sh/uv/guides/install-python/) command.

```
uv python install <PYTHON_VERSION>
```

For example, if you choose Python 3.14, run `uv python install 3.14`. Afterward, verify the Python installation using the command below.

```
uv python list --only-installed
```

Make sure to install a recent version of Python to avoid any compatibility issues.


## Step 3: Set up a project

Create a new folder and navigate to it in the terminal. You can choose any folder name; the example below uses `deep-learning`.

```
mkdir deep-learning
cd deep-learning
```

Then, initialize the project using the [`uv init`](https://docs.astral.sh/uv/guides/projects/) command.

```
uv init --bare
```

If you have several Python versions installed and want to force uv to use one specific version, add the `--python` option.

```
uv init --bare --python <PYTHON_VERSION>
```

This will create a `pyproject.toml` file in your project directory. By default, the project name is taken from the folder name. For example, the file will look like this.

```toml
[project]
name = "deep-learning"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = []
```

The first time you run a project command, uv will create a virtual environment and a [`uv.lock`](https://docs.astral.sh/uv/concepts/projects/layout/#the-project-environment) file in the project directory. Run the following command as an example.

```
uv sync
```

After running the command, your project structure will look like this.

```
deep-learning
│
├── .venv
│   ├── bin/
│   ├── lib/
│   └── ...
│
├── pyproject.toml
└── uv.lock
```

:::{admonition} Version Control
The project configuration (`pyproject.toml`) and the lockfile (`uv.lock`) should be included in version control if you are working on your own project. They make the environment reproducible on other machines. The virtual environment (`.venv`) should not be included, as it can be recreated automatically by uv.
:::


## Step 4: Install dependencies

The `pyproject.toml` file contains metadata about your project. You will use this file to specify dependencies and other details about the environment. You can edit this file manually, but it is recommended to use uv commands to [manage dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/), as they also update the lockfile and the virtual environment.

- `uv add <PACKAGE>` - Add a dependency to the project.

- `uv remove <PACKAGE>` - Remove a dependency from the project.

### Basic dependencies

Start with the installation of common third-party packages for data science and machine learning.

```
uv add numpy pandas matplotlib scikit-learn opencv-python notebook gdown tqdm
```

The packages `numpy`, `pandas`, and `matplotlib` are used for numerical work, tabular data, and plotting, `scikit-learn` provides a wide range of machine learning algorithms, `opencv-python` is used for computer vision tasks, `notebook` provides the local Jupyter Notebook interface, `gdown` allows downloading files from Google Drive, and `tqdm` provides progress bars for longer-running loops.

### PyTorch

PyTorch is installed through the `torch` package, which provides a comprehensive set of tools for deep learning. TorchVision is a companion package that provides datasets, model architectures, and image transformations for computer vision tasks. The following command

```
uv add torch torchvision
```

installs platform-specific builds of PyTorch and TorchVision.
- On Windows, the CPU version is installed.
- On Linux, the CUDA version is installed.
- On Macs with Apple Silicon, the MPS version is installed if supported, otherwise the CPU version.
- On Macs with Intel processors, the installation fails.

To change the default behavior, you can add a custom source to `pyproject.toml` before running the `uv add` command. The following sections provide examples for Windows with NVIDIA GPUs and Intel Macs. The uv documentation provides more details in its [PyTorch installation guide](https://docs.astral.sh/uv/guides/integration/pytorch/#installing-pytorch).

#### Windows CUDA

PyTorch can be installed from a custom package index that hosts CUDA-accelerated wheels for Windows. In this case, add the PyTorch CUDA index to `pyproject.toml` before running the `uv add` command.

```toml
# On Windows, torch and torchvision are fetched from a custom repository
[tool.uv.sources]
torch = [
  { index = "pytorch-cuda", marker = "sys_platform == 'win32'" },
]
torchvision = [
  { index = "pytorch-cuda", marker = "sys_platform == 'win32'" },
]

# Defining the index "pytorch-cuda"
[[tool.uv.index]]
name = "pytorch-cuda"
url = "https://download.pytorch.org/whl/cu132"
explicit = true
```

You also need to install an **NVIDIA driver compatible with the CUDA version** used by the PyTorch wheels. Then, run the following command

```
uv add torch torchvision
```

to install PyTorch and TorchVision with CUDA support.

#### MacOS Intel

PyTorch stopped providing official pre-built binaries for MacOS on Intel processors. In this case, you need to download a compatible wheel and tell uv to use that local file when installing `torch`. One possible source is [PyTorch-MacOS-Builder](https://github.com/Morton-Li/PyTorch-MacOS-Builder) for PyTorch and [TorchVision-MacOS-Builder](https://github.com/Morton-Li/TorchVision-MacOS-Builder) for TorchVision.

**Download the wheels that match your Python version and your platform.** Place them inside your project folder. For example, you can create a `wheels` folder.

```
deep-learning
│
├── wheels
│   ├── torch-<VERSION>-<PYTHON_TAG>-<PLATFORM_TAG>.whl
│   └── torchvision-<VERSION>-<PYTHON_TAG>-<PLATFORM_TAG>.whl
│
├── pyproject.toml
└── uv.lock
```

Then, open `pyproject.toml` and add a source entry for `torch` and `torchvision`. Replace the filenames below with the exact names of the wheels you downloaded.

```toml
# On Intel Macs, torch and torchvision are installed from local wheels.
[tool.uv.sources]
torch = [
  {
    path = "wheels/torch-<VERSION>-<PYTHON_TAG>-<PLATFORM_TAG>.whl",
    marker = "sys_platform == 'darwin' and platform_machine == 'x86_64'"
  },
]
torchvision = [
  {
    path = "wheels/torchvision-<VERSION>-<PYTHON_TAG>-<PLATFORM_TAG>.whl",
    marker = "sys_platform == 'darwin' and platform_machine == 'x86_64'"
  },
]
```

Once this source is configured, run the following command

```
uv add torch torchvision
```

to install PyTorch and TorchVision from the local wheels.

:::{note}
You may have multiple wheels for different platforms. In that case, you can add multiple entries to the `torch` and `torchvision` source lists, each with its own `marker` to specify the platform.

```toml
[tool.uv.sources]
torch = [
  {
    path = "wheels/torch-<VERSION>-<PYTHON_TAG>-<PLATFORM_TAG>.whl",
    marker = "sys_platform == 'darwin' and platform_machine == 'x86_64'"
  },
  {
    index = "pytorch-cuda",
    marker = "sys_platform == 'win32'"
  },
]
torchvision = [
  {
    path = "wheels/torchvision-<VERSION>-<PYTHON_TAG>-<PLATFORM_TAG>.whl",
    marker = "sys_platform == 'darwin' and platform_machine == 'x86_64'"
  },
  {
    index = "pytorch-cuda",
    marker = "sys_platform == 'win32'"
  },
]

[[tool.uv.index]]
name = "pytorch-cuda"
url = "https://download.pytorch.org/whl/cu132"
explicit = true
```
:::

### Other libraries

Configure the intended PyTorch package source before adding libraries that depend on PyTorch. This ensures that `uv` resolves them against the correct PyTorch build. Some of the tutorials in this course use the library `torcheval` for evaluating machine learning models and `torchinfo` for inspecting PyTorch models. You can install them using the regular `uv add` command.

```
uv add torcheval torchinfo
```

From this point on, you can install any other libraries you need for your project using the `uv add` command. 


## Step 5: Verify the installation

You can verify the main libraries by opening a Python terminal from the project environment.

```
uv run python
```

Then run the following code.

```python
import torch
import torchvision

print("PyTorch:", torch.__version__)
print("TorchVision:", torchvision.__version__)

if torch.cuda.is_available():
    print("Accelerator: CUDA")
elif torch.mps.is_available():
    print("Accelerator: MPS")
else:
    print("Accelerator: CPU")
```

If this code runs without errors, the main libraries are available in your environment. The final line reports whether PyTorch can see a GPU accelerator or will run on CPU.




<!--

# Legacy Installation (not recommended)

This section provides instructions for installing PyTorch in a virtual environment using `pyenv` and `virtualenv`. This method is not recommended for new projects, as it requires manual management of Python versions and dependencies. It is included here for reference only, as the `uv` tool is now the preferred method for managing Python projects.

## Install [pyenv](https://github.com/pyenv/pyenv)

  - MacOS (using [Homebrew](https://brew.sh/))
    ```
    brew install pyenv
    ```

  - [Windows](https://github.com/pyenv-win/pyenv-win)
    ```
    Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
    ```
    If you are getting any UnauthorizedAccess error, start Windows PowerShell with the "Run as administrator" option and execute 
    ```
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
    ```
    Then run the installation command again.


## Install Python 3.12

Execute the following commands in the project directory. On Windows, you may need to open PowerShell with the "Run as administrator" option.

```
pyenv install 3.12.8
pyenv local 3.12.8
```

Check that the correct version of Python is being used.

```
python --version
pip --version
```

## Install a virtual environment

Execute the following commands in the project directory.

```
pip install virtualenv
virtualenv .env
```

## Activate the virtual environment

Before installing any packages, you need to activate the virtual environment.

- MacOS/Linux
  ```
  source .env/bin/activate
  ```

- Windows
  ```
  .env\Scripts\activate
  ```

## Install dependencies

Execute the following command in a terminal with the virtual environment activated.

```
pip install numpy matplotlib scikit-learn opencv-python notebook tqdm
```

## Install PyTorch

Execute the following commands in a terminal with the virtual environment activated.

- MacOS ARM or Windows without GPU
  ```
  pip install torch torchvision
  ```

- Windows with NVIDIA GPU
  ```
  pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
  ```
  You also need to install [CUDA Toolkit 12.4.1](https://developer.nvidia.com/cuda-toolkit-archive).

-->