🐛 fix(pip): skip constrain_package_deps when constraints is set (#3948)

When both `constraints` and `constrain_package_deps = true` are
configured, tox passes two `-c` flags to pip during
`install_package_deps`: one for the user's constraints file and one for
the auto-generated constraints file. 🔧 pip merges constraints from
multiple files via specifier intersection, so overlapping packages with
different versions produce unsatisfiable constraints and a resolver
error.

The `constraints` option already applies to both `install_deps` and
`install_package_deps` phases, making `constrain_package_deps` redundant
when it is set. This change skips generating and applying the
auto-generated constraints file whenever user constraints are
configured. The three affected code paths (non-frozen write, frozen
write, and package_deps application) all gate on a new
`_has_constraints` property that checks whether the user provided
constraint content.

Users who currently set both options will see the same effective
behavior, minus the conflicting duplicate `-c` flag. If they relied on
auto-constraining for packages absent from their constraints file, they
should add those pins to their constraints file directly.

Fixes #3945

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: gaborbernat

docs/changelog/3945.bugfix.rst

@@ -0,0 +1,4 @@
+When the ``constraints`` configuration option is set, ``constrain_package_deps`` and ``use_frozen_constraints`` are now
+ignored. Previously, both the user-provided constraints file and the auto-generated constraints file were passed to pip
+during ``install_package_deps``, which could cause resolver conflicts when the same package appeared in both files - by
+:user:`gaborbernat`. (:issue:`3945`)

docs/how-to/usage.rst

@@ -763,6 +763,13 @@ error when package dependencies conflict with test dependencies.
 For stronger guarantees, set ``use_frozen_constraints = true`` to generate constraints from the exact installed versions
 (via ``pip freeze``). This catches incompatibilities with any previously installed dependency.
 
+.. note::
+
+    When :ref:`constraints` is set, ``constrain_package_deps`` and ``use_frozen_constraints`` have no effect. The
+    :ref:`constraints` option already applies to both ``install_deps`` and ``install_package_deps`` phases, so the
+    auto-generated constraints file is not created. If you need to pin specific dependency versions during package
+    installation, add them to your constraints file directly.
+
 .. note::
 
     Constraint files are a subset of requirement files. You can pass a constraint file wherever a requirement file is

docs/onboarding.rst

@@ -746,7 +746,8 @@ The concrete installer (`tox_env/python/pip/ <https://github.com/tox-dev/tox/blo
 has the following features:
 
 - **Incremental installs** compare new vs cached requirements and only install changes.
-- It supports ``pip_pre``, constraints, and ``use_frozen_constraints``.
+- It supports ``pip_pre``, constraints, and ``use_frozen_constraints``. When the ``constraints`` option is set, it takes
+  precedence over ``constrain_package_deps``/``use_frozen_constraints``.
 - The ``{packages}`` placeholder in ``install_command`` is replaced with actual arguments.
 - See :ref:`exec-execution` for how installation commands are executed.
 

docs/reference/config.rst

@@ -2068,6 +2068,9 @@ Pip installer
     package dependencies during ``install_package_deps`` stage. When this value is set to false, any conflicting package
     dependencies will override explicit dependencies and constraints passed to :ref:`deps`.
 
+    This option has no effect when :ref:`constraints` is set, as the constraints option already applies to package
+    dependency installation.
+
 .. conf::
     :keys: use_frozen_constraints
     :default: false
@@ -2076,7 +2079,7 @@ Pip installer
     When ``use_frozen_constraints`` is true, then tox will use the ``list_dependencies_command`` to enumerate package
     versions in order to create ``{env_dir}{/}constraints.txt``. Otherwise the package specifications explicitly listed
     under ``deps`` (or in requirements / constraints files referenced in ``deps``) will be used as the constraints. If
-    ``constrain_package_deps`` is false, then this setting has no effect.
+    ``constrain_package_deps`` is false or :ref:`constraints` is set, then this setting has no effect.
 
 ********************
  User configuration

src/tox/tox_env/python/pip/pip_install.py

@@ -200,7 +200,7 @@ def _install_requirement_file(self, arguments: PythonDeps, section: str, of_type
                 if args:  # pragma: no branch
                     args.extend(self.constraints.as_root_args)
                     self._execute_installer(args, of_type)
-                    if self.constrain_package_deps and not self.use_frozen_constraints:
+                    if self.constrain_package_deps and not self.use_frozen_constraints and not self._has_constraints:
                         combined_constraints = new_requirements + [c.removeprefix("-c ") for c in new_constraints]
                         self.constraints_file().write_text("\n".join(combined_constraints))
 
@@ -288,8 +288,12 @@ def _apply_force_deps(self, deps: Sequence[Requirement]) -> list[str]:
         forced: dict[str, Requirement] = {r.name: r for r in getattr(self._env.options, "force_dep", [])}
         return [str(forced.get(dep.name, dep)) for dep in deps]
 
+    @property
+    def _has_constraints(self) -> bool:
+        return bool(self.constraints.lines())
+
     def _execute_installer(self, deps: Sequence[Any], of_type: str) -> None:
-        if of_type == "package_deps" and self.constrain_package_deps:
+        if of_type == "package_deps" and self.constrain_package_deps and not self._has_constraints:
             constraints_file = self.constraints_file()
             if constraints_file.exists():
                 deps = [*deps, f"-c{constraints_file}"]
@@ -298,8 +302,12 @@ def _execute_installer(self, deps: Sequence[Any], of_type: str) -> None:
         outcome = self._env.execute(cmd, stdin=StdinSource.OFF, run_id=f"install_{of_type}")
         outcome.assert_success()
 
-        if of_type == "deps" and self.constrain_package_deps and self.use_frozen_constraints:
-            # freeze installed deps for use as constraints
+        if (
+            of_type == "deps"
+            and self.constrain_package_deps
+            and self.use_frozen_constraints
+            and not self._has_constraints
+        ):
             self.constraints_file().write_text("\n".join(self.installed()))
 
     def build_install_cmd(self, args: Sequence[str]) -> list[str]:

tests/tox_env/python/pip/test_pip_install.py

@@ -457,6 +457,54 @@ def test_constrain_package_deps(
         assert not constraints_file.exists()
 
 
+@pytest.mark.parametrize("use_frozen_constraints", [True, False])
+def test_constraints_option_disables_constrain_package_deps(
+    tox_project: ToxProjectCreator,
+    demo_pkg_inline: Path,
+    use_frozen_constraints: bool,
+) -> None:
+    toml = (demo_pkg_inline / "pyproject.toml").read_text()
+    proj = tox_project({
+        "pyproject.toml": toml.replace("requires = []", 'requires = ["setuptools"]')
+        + '\n[project]\nname = "demo"\nversion = "0.1"\ndependencies = ["foo > 2"]',
+        "build.py": (demo_pkg_inline / "build.py").read_text(),
+        "constraints.txt": "coo==1.2.3",
+        "tox.ini": (
+            "[testenv]\npackage=wheel\n"
+            "constrain_package_deps = true\n"
+            f"use_frozen_constraints = {use_frozen_constraints}\n"
+            "deps = coo==1.2.3\n"
+            "constraints = constraints.txt"
+        ),
+    })
+    execute_calls = proj.patch_execute(lambda r: 0 if "install" in r.run_id else None)
+    result = proj.run("r")
+    result.assert_success()
+
+    constraints_file = proj.path / ".tox" / "py" / "constraints.txt"
+    assert not constraints_file.exists()
+
+    for call in execute_calls.call_args_list:
+        if call[0][3].run_id == "install_package_deps":
+            cmd = call[0][3].cmd
+            assert f"-c{constraints_file}" not in cmd
+            assert "-c" in cmd
+            assert "constraints.txt" in cmd
+
+    exp_run_ids = ["install_deps"]
+    exp_run_ids.extend([
+        "install_requires",
+        "_optional_hooks",
+        "get_requires_for_build_wheel",
+        "build_wheel",
+        "install_package_deps",
+        "install_package",
+        "_exit",
+    ])
+    run_ids = [i[0][3].run_id for i in execute_calls.call_args_list]
+    assert run_ids == exp_run_ids
+
+
 def test_pip_resolution_env_var_change_reinstalls(tox_project: ToxProjectCreator) -> None:
     proj = tox_project({
         "tox.ini": """