Installation

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, 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)

    brew install uv

  • Windows (using PowerShell)

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

  • See the uv documentation 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 command allows you to see installed and available Python versions.

uv python list

You can install Python using the uv python install 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 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.

[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 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

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, 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.

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.

# 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 for PyTorch and 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.

# 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.

[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.

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.