`--bounds` has no effect for `--script`

[nik-sm]

Summary

It seems that uv add --bounds exact has no effect when adding dependencies to a script. See example below. If this is intended behavior, I believe the CLI should warn about this.

$ uv init --script example.py                      
Initialized script at `example.py`
$ uv add --script example.py --bounds exact ipython
warning: The `bounds` option is in preview and may change in any future release. Pass `--preview-features add-bounds` to disable this warning.
Updated `example.py`

$ cat example.py 
───────┬─────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "ipython",
   5   │ # ]
   6   │ # ///
   7   │ 
   8   │ 
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │ 
  12   │ 
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────



$ uv init --script example2.py                     
Initialized script at `example2.py`

$ uv add --script example2.py --bounds major ipython
warning: The `bounds` option is in preview and may change in any future release. Pass `--preview-features add-bounds` to disable this warning.
Updated `example2.py`
$ cat example2  
[bat error]: 'example2': No such file or directory (os error 2)

$ cat example2.py 
───────┬──────────────────────────────────────
       │ File: example2.py
───────┼──────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "ipython",
   5   │ # ]
   6   │ # ///
   7   │ 
   8   │ 
   9   │ def main() -> None:
  10   │     print("Hello from example2.py!")
  11   │ 
  12   │ 
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴──────────────────────────────────────

P.S. loving the --script workflow - keep up the great work!

Platform

Darwin 24.5.0 arm64

Version

uv 0.8.13 (ede75fe 2025-08-21)

Python version

Python 3.12.11

[charliermarsh]

I suspect this works if you run uv lock --script example.py first. Without a lockfile, uv add --script just adds the verbatim dependency. Agree we should warn.

[konstin]

For my use cases, I'd like to have e.g. uv add httpx --script foo.py --bounds major add numpy with bounds. There are cases where you don't want or can't use a lockfile, but you still want some bounds to avoid sudden breakage. It feels odd to ignore an explicit option depending on whether a lockfile exists. The same applies to uv add pandas --bounds major --frozen.

[zanieb]

Huh why aren't we using bounds by default in scripts unless there's a lockfile? That seems surprising.

[charliermarsh]

Because it would require performing a resolution, and we don't perform any resolution if there isn't a lockfile.

[zanieb]

I think that's probably wrong in general, e.g., we allow you to add conflicting dependencies? (or am I missing something here?)

[nik-sm]

For me, the single-file simplicity is part of the appeal of the --script workflow. That being said, I don't know how much of a challenge it is to resolve versions without a lockfile or whether it leads to other problems.

Just testing a bit more, is seems this feature may not be working either way. All I changed below is doing uv lock --script file.py before uv add --bounds exact numpy --script file.py but it still doesn't seem to work. Maybe there is another option I'm supposed to pass to ensure lockfile is discovered/used?

Example using 0.8.13

✓ Desktop % uv init --script example.py
Initialized script at `example.py`
✓ Desktop % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = []
   4   │ # ///
   5   │
   6   │
   7   │ def main() -> None:
   8   │     print("Hello from example.py!")
   9   │
  10   │
  11   │ if __name__ == "__main__":
  12   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ Desktop % uv add --bounds exact numpy --script example.py
warning: The `bounds` option is in preview and may change in any future release. Pass `--preview-features add-bounds` to disable this warning.
Updated `example.py`
✓ Desktop % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "numpy",
   5   │ # ]
   6   │ # ///
   7   │
   8   │
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │
  12   │
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ Desktop % uv lock --script example.py
Resolved 1 package in 6ms
✓ Desktop % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "numpy",
   5   │ # ]
   6   │ # ///
   7   │
   8   │
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │
  12   │
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ Desktop % wc -l example.py.lock
      69 example.py.lock
✓ Desktop % uv add --bounds exact numpy --script example.py
warning: The `bounds` option is in preview and may change in any future release. Pass `--preview-features add-bounds` to disable this warning.
Resolved 1 package in 2ms
✓ Desktop % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "numpy",
   5   │ # ]
   6   │ # ///
   7   │
   8   │
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │
  12   │
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ Desktop %

Example using 0.8.14

✓ tmp % uv init --script example.py
Initialized script at `example.py`
✓ tmp % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = []
   4   │ # ///
   5   │
   6   │
   7   │ def main() -> None:
   8   │     print("Hello from example.py!")
   9   │
  10   │
  11   │ if __name__ == "__main__":
  12   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ tmp % uv add --bounds exact numpy --script example.py
warning: The `bounds` option is in preview and may change in any future release. Pass `--preview-features add-bounds` to disable this warning.
Updated `example.py`
✓ tmp % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "numpy",
   5   │ # ]
   6   │ # ///
   7   │
   8   │
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │
  12   │
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ tmp % uv lock --script example.py
Resolved 1 package in 4ms
✓ tmp % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "numpy",
   5   │ # ]
   6   │ # ///
   7   │
   8   │
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │
  12   │
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────────────────────────────
✓ tmp % wc -l example.py.lock
      69 example.py.lock
✓ tmp % uv add --bounds exact numpy --script example.py
warning: The `bounds` option is in preview and may change in any future release. Pass `--preview-features add-bounds` to disable this warning.
Resolved 1 package in 2ms
✓ tmp % cat example.py
───────┬─────────────────────────────────────────────────────────────
       │ File: example.py
───────┼─────────────────────────────────────────────────────────────
   1   │ # /// script
   2   │ # requires-python = ">=3.12"
   3   │ # dependencies = [
   4   │ #     "numpy",
   5   │ # ]
   6   │ # ///
   7   │
   8   │
   9   │ def main() -> None:
  10   │     print("Hello from example.py!")
  11   │
  12   │
  13   │ if __name__ == "__main__":
  14   │     main()
───────┴─────────────────────────────────────────────────────────────

[nik-sm]

Just a ping with more info about --bounds. In version 0.8.14 and in latest (0.8.17), the behavior is like this:

uv init --script file.py
uv add --script file.py --bounds exact numpy    # does not include bounds
uv lock --script file.py
uv add --script file.py --bounds exact loguru   # this works (add NEW package with bounds)
uv add --script file.py --bounds exact numpy    # this does nothing (add EXISTING package with bounds)

The behavior seems to be the same for --script and for regular uv projects (i.e. the result of plain uv init).

In both situations (a uv init project, or a uv init --script; uv lock --script), uv does resolve dependencies, but then exits 0 without making changes.

Not sure whether this is intentional vs bug, but I think it's unintuitive. (uv add numpy==2.3.3 will always try to apply the requested version logic as you expect, but uv add numpy --bounds exact sometimes does NOT try to apply the requested version logic...)