Python: UV and Pants Monorepo Setup

Table of Contents

• Python Structure
• 0) Repo layout you’ll end up with
• 1) Initialize with uv
• 2) Configure deps so Pants can read them (uv_requirements)
• 3) Add Pants
• 4) Add BUILD files
  • Root BUILD
  • 3rdparty/BUILD
  • lib_math/BUILD
  • math/BUILD
  • tests/math/BUILD
• 5) Add the Python code
  • lib_math/utils/__init__.py
  • lib_math/utils/core.py
  • math/scripts/__init__.py
  • math/scripts/main.py
  • tests/math/test_main.py
• 6) Generate the Pants lockfile + run

Python Structure

uv + Pants Python Monorepo Guide (lib_math, math scripts, tests)

0) Repo layout you’ll end up with

.
├── pants.toml
├── pyproject.toml
├── BUILD
├── 3rdparty/
│   └── BUILD
├── lib_math/
│   ├── BUILD
│   └── utils/
│       ├── __init__.py
│       └── core.py
├── math/
│   ├── BUILD
│   └── scripts/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── math/
        ├── BUILD
        └── test_main.py

Note: naming a top-level package math can shadow the Python stdlib math. If that’s a problem for you, rename the folder/package (e.g. math_pkg). I’ll follow your requested layout as-is.

---

1) Initialize with uv

mkdir myrepo && cd myrepo
uv init --bare
uv add --dev pytest

This creates pyproject.toml and uv.lock.

---

2) Configure deps so Pants can read them (uv_requirements)

Pants has a uv_requirements target that generates python_requirement targets from entries under [tool.uv] in pyproject.toml.

Edit pyproject.toml to include at least your dev deps there:

[project]
name = "myrepo"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []

[tool.uv]
dev-dependencies = [
  "pytest>=8",
]

---

3) Add Pants

Create pants.toml:

[GLOBAL]
pants_version = "2.30.0"
backend_packages = [
  "pants.backend.python",
]

[python]
interpreter_constraints = ["CPython>=3.11,<3.13"]
enable_resolves = true
default_resolve = "python-default"
resolves = { python-default = "3rdparty/python-default.lock" }

[pytest]
install_from_resolve = "python-default"

---

4) Add BUILD files

Root BUILD

# (optional) keep empty or add repo-wide targets later

3rdparty/BUILD

This reads [tool.uv] from your root pyproject.toml and generates requirement targets.

uv_requirements(
    name="reqs",
    source="../pyproject.toml",
    resolve="python-default",
)

lib_math/BUILD

python_sources(name="lib_math")

math/BUILD

python_sources(name="math")

pex_binary(
    name="run",
    entry_point="math.scripts.main:main",
    resolve="python-default",
)

tests/math/BUILD

python_tests(
    name="tests",
    resolve="python-default",
)

---

5) Add the Python code

lib_math/utils/__init__.py

from .core import add

__all__ = ["add"]

lib_math/utils/core.py

def add(a: float, b: float) -> float:
    return a + b

math/scripts/__init__.py

math/scripts/main.py

from lib_math.utils import add


def main() -> None:
    print(add(2, 3))


if __name__ == "__main__":
    main()

tests/math/test_main.py

from lib_math.utils import add


def test_add() -> None:
    assert add(2, 3) == 5

---

6) Generate the Pants lockfile + run

Generate lockfiles for your resolve:

pants generate-lockfiles --resolve=python-default

Run your script (PEX):

pants run math:run

Run tests:

pants test tests/math::