# pip and uv

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/start/environments/pip-and-uv/
Language: en
Alternate: https://docs.jmrp.io/phonometry/es/start/environments/pip-and-uv/index.md
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Unreleased: this page changed after phonometry 4.0.0, the latest release on PyPI, so it may describe code that release does not have yet; what is new since then is listed under Unreleased in https://github.com/jmrplens/phonometry/blob/main/CHANGELOG.md#unreleased
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-11-11
Updated: 2026-11-18T01:01:07Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Install phonometry with pip or uv on Python 3.12 to 3.14: each extra and what it brings, torch without CUDA, a uv project and an install from a clone.

---

phonometry installs from PyPI with [pip](https://pip.pypa.io/en/stable/) or
[uv](https://docs.astral.sh/uv/) on Python 3.12, 3.13 and 3.14, as one wheel
with no compiled code of its own. Both tools land on the same packages; the
difference is how they keep a project's dependencies, and how each is told to
take torch from PyTorch's CPU index.

Checked on 17 November 2026 with phonometry 4.0.0 from PyPI, in the
`python:3.12-slim`, `python:3.13-slim` and `python:3.14-slim` images, on
Python 3.12.16, 3.13.18 and 3.14.10: pip 26.3 with NumPy 2.5.5 and SciPy
1.18.1, uv 0.13.9 on Python 3.13.18, and torch 2.15.0 from PyTorch's CPU
index.

## pip in a virtual environment

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "phonometry[full]"
```

On Windows the environment is activated with `.venv\Scripts\activate.bat`
in cmd or `.venv\Scripts\Activate.ps1` in PowerShell in place of
`source .venv/bin/activate`, here and in the block of a clone below.
PowerShell on a Windows client refuses scripts under its default
execution policy, so `Activate.ps1` runs there once
`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` has allowed local ones;
cmd needs no such step.

`python -m pip install phonometry` alone brings NumPy and SciPy and nothing
else; that is enough for every metric of the library. `python -m pip check`
reports no broken requirement afterwards, with or without extras. Check what
the environment imports:

```python
import phonometry

print(phonometry.__version__)   # the release you installed
```

## What each extra brings

| Extra | Brings | So that |
|---|---|---|
| `[plot]` | matplotlib | `.plot()` and the filter response plots draw |
| `[report]` | reportlab, svglib | `.report()` writes a PDF fiche; its figure panel also needs `[plot]` |
| `[audio]` | python-soundfile, whose wheel carries libsndfile except on the platforms named below | `phonometry.io` reads FLAC, AIFF, Ogg/Opus, MP3 and compressed WAV, and writes FLAC |
| `[perf]` | numba | the `impulse` time weighting runs compiled |
| `[full]` | all four above | every feature but the torch backend |
| `[torch]` | torch, array-api-compat | the FDTD engines step on PyTorch |

On a bare `python:3.13-slim` image for x86-64 or ARM64 no extra needs a
system package: every one of them installs and runs from its wheels there,
`[audio]` included. The image's six other architectures have no wheel of
NumPy, SciPy, matplotlib or Pillow, so pip builds them from source there, and
`[audio]` loads the system's libsndfile. numba supports none of its three
32-bit ones, so `[perf]` and `[full]` are not supported there, and torch
publishes no wheel for any of the six and no source, so `[torch]` does not
install there from PyPI; [Docker and
servers](https://docs.jmrp.io/phonometry/start/environments/docker/) says what the rest takes.
Without numba the `impulse` time weighting runs as plain Python and says
nothing about it. A feature whose extra is missing says which one to install,
with its pip and its conda spelling:

```text
ImportError: Plotting requires matplotlib. Install it with: pip install "phonometry[plot]" (conda: conda install -c conda-forge matplotlib-base)
```

The oldest release of each dependency the library is tested with, on each
Python, is listed in [Getting
Started](https://docs.jmrp.io/phonometry/start/getting-started/#from-pypi-recommended). On Windows
on ARM, on Linux with musl, on macOS on Intel and on 32-bit Windows, some of
those releases have no wheel, and pip builds them from source there, as even a
plain install does with SciPy on 32-bit Windows, and as `[plot]` does with
matplotlib on Linux on ARM with musl and on 32-bit Windows; that section
names which. numba no longer supports 32-bit Windows, nor 32-bit Linux, so
neither `[perf]` nor `[full]`, which holds it, is supported on either, where
`python -m pip install "phonometry[plot,report,audio]"` installs the other
three extras. torch publishes no source to build, so it installs on none of
the four from PyPI, and on Windows on ARM from PyTorch's CPU index, as the
next section does. python-soundfile publishes no wheel that carries libsndfile
for Linux with musl, nor at its floor for Linux on ARM or Windows on ARM, so
`[audio]` loads the system's libsndfile there: on Alpine,
`apk add libsndfile-dev`.

## torch without CUDA

`[full]` leaves `[torch]` out, because the torch wheels PyPI serves on Linux
bring gigabytes of CUDA libraries. On a Linux machine without an NVIDIA GPU,
install torch from PyTorch's CPU index first, then the extra, which keeps the
torch it finds, in the virtual environment made above. On Windows on ARM,
where PyPI has no torch, the same two commands bring `[torch]` on Python 3.12
and 3.13, from torch 2.7.0 and 2.8.0:

```bash
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install "phonometry[torch]"
```

The environment then holds the CPU build of torch and no NVIDIA package, and
an FDTD run on `Compute(device="torch:cpu")` gives the same pressures as the
NumPy run. [Where a simulation runs](https://docs.jmrp.io/phonometry/simulation/compute/) covers the
other devices.

## From a clone

```bash
git clone https://github.com/jmrplens/phonometry.git
cd phonometry
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .
```

pip builds the wheel with setuptools and no compiler, and the build also
passes under `PYTHONWARNINGS=error`.

## uv

`uv pip` takes the same requirements as pip, in an environment uv creates:

```bash
uv venv
uv pip install "phonometry[full]"
```

For torch, `--torch-backend cpu` tells uv to take torch from PyTorch's CPU
index, with no NVIDIA package:

```bash
uv pip install "phonometry[torch]" --torch-backend cpu
```

In a uv project, `uv add` writes the requirement into `pyproject.toml` and the
lock file, and `uv run` runs in the project's environment:

```bash
uv init acoustics
cd acoustics
uv add "phonometry[full]"
uv run python -c "import phonometry; print(phonometry.__version__)"
```

`uv add` resolves the same way in a project for Python 3.12, 3.13 or 3.14.
On 32-bit Windows and 32-bit Linux, where `[full]` is not supported, name
`[plot,report,audio]` in its place, with `uv pip install` as with `uv add`; uv
builds from source there what pip does, SciPy, matplotlib and kiwisolver on
32-bit Windows, and on 32-bit Linux the packages [Docker and
servers](https://docs.jmrp.io/phonometry/start/environments/docker/) names.

### torch from the CPU index in a project

Name the index in `pyproject.toml`, mark it explicit so that only torch is
taken from it, and route torch to it:

```toml
[tool.uv.sources]
torch = [{ index = "pytorch-cpu" }]

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

Then add torch by name beside the extra:

```bash
uv add "phonometry[torch]" torch
```

The name matters. A source applies to a dependency the project names itself,
so `uv add "phonometry[torch]"` alone, with the same `pyproject.toml`, locks
the torch of PyPI's default index together with its CUDA and NVIDIA packages,
and says nothing about it.
