Installation

Installation#

Last updated: 23-09-2025

This guide provides instructions for setting up PyTorch on your local machine in an isolated environment. 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 3.12, the setup of a project, the addition of various Python libraries, and the installation of PyTorch on different platforms.

Step 1: Install uv#

MacOS (using Homebrew)
```
brew install uv
```

Windows (using PowerShell)

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

See the documentation for other installation methods.

After the installation, close and reopen the terminal to apply the changes, then confirm that uv is available by running the uv command. (If you are working in Visual Studio Code, you need to restart the editor as well.)

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 (guide) allows you to see both the installed and the available Python versions.

uv python list

You can install Python using the uv python install command (guide). PyTorch requires Python 3.12 at the time of writing this guide, which you can install as follows.

uv python install 3.12

Verify the Python installation using the command below.

uv python list --only-installed

Step 3: Set up a project#

Create a new folder for your project and navigate to it in the terminal. Then, initialize the project using the init command (guide) with the desired Python version.

uv init --bare --python 3.12

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

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
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.

my-project
│
├── .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 to ensure that the project can be reproduced on other machines. The virtual environment (.venv) can be excluded, as it will be recreated automatically by uv.

Step 4: Install dependencies#

The pyproject.toml contains metadata about your project. You will use this file to specify dependencies and other details about the project. You can edit this file manually, but it’s 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.
uv lock --upgrade-package <PACKAGE> - Upgrade a package to the latest compatible version, while keeping the rest of the lockfile intact.

This command adds several common libraries for machine learning and data science to the project.

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

Step 5: Install PyTorch#

PyTorch provides pre-built binaries for various platforms and accelerators, but they are published to different package indexes than the default PyPI. As such, the project configuration will vary depending on both the platforms you need to support and the accelerators you want to enable. (For more information on this topic, the uv documentation provides a detailed installation guide.)

Windows (CPU only) - MacOS ARM#

PyTorch can be installed from PyPI, which hosts CPU-only wheels for Windows, and MPS-accelerated wheels for MacOS with ARM processor. In this case, you simply add PyTorch and TorchVision to the project.

uv add torch torchvision torcheval torchinfo

Windows (with NVIDIA GPU)#

PyTorch can be also installed from a custom package index that hosts CUDA-accelerated wheels for Windows. In this case, you need to specify the index in the project configuration.

Open the pyproject.toml file and add the following lines.

# On Windows, torch and torchvision are fetched from a custom index 
# The custom index is referenced by the name "pytorch-cu126" in this config
[tool.uv.sources]
torch = [
  { index = "pytorch-cu126", marker = "sys_platform == 'win32'" },
]
torchvision = [
  { index = "pytorch-cu126", marker = "sys_platform == 'win32'" },
]

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

Add PyTorch and TorchVision to the project.

uv add torch torchvision torcheval torchinfo

Install CUDA Toolkit 12.6.

MacOS x86#

Unfortunately, PyTorch no longer provides pre-built binaries for MacOS x86. You have two options to install PyTorch on MacOS x86: either install an older version of PyTorch or compile from source.

Install an older version of PyTorch#

You can allow older versions to be installed by declaring explicit support for non-latest platforms, since this often requires backtracking past the latest published versions of those packages.

Open the pyproject.toml file and add the following lines.

[tool.uv]
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'x86_64'"
]

Add PyTorch and TorchVision to the project.

uv add torch torchvision torcheval torchinfo

This will install the last version of PyTorch that was released for MacOS x86. However, please note that this version may not be the latest release and may not include all the features and improvements available in the latest version, such as support for MPS acceleration.

Compile from source#

Alternatively, you can build local wheels for PyTorch and TorchVision from the source code.

Compile the wheels for PyTorch and TorchVision (see the instructions below).

Add the wheels to the project, adjusting the filenames based on the versions you built.

uv add torch-2.5.1-cp312-cp312-macosx_15_0_x86_64.whl
uv add torchvision-0.22.0a0+d3beb52-cp312-cp312-macosx_15_0_x86_64.whl
uv add torcheval torchinfo

This is the recommended option if you want to use the latest features and improvements available in PyTorch. However, this process can be complex and time-consuming.

Compile from source (MacOS x86)#

PyTorch#

Follow these instructions to build PyTorch from source.

Clone the git repository
Create a virtual environment and activate it

Install the dependencies

pip install -r requirements.txt mkl-static mkl-include

Build the wheel

env USE_CUDA=0 PYTORCH_BUILD_VERSION=2.5.1 PYTORCH_BUILD_NUMBER=0 python setup.py bdist_wheel

TorchVision#

Follow these instructions to build TorchVision from source.

Clone the git repository
Create a virtual environment and activate it

Install NumPy and PyTorch (from the wheel built previously)

pip install numpy
pip install torch-2.5.1-cp312-cp312-macosx_15_0_x86_64.whl

Install ninja using Homebrew
```
brew install ninja
```