uv add and uv add -r fail with misleading 'No pyproject.toml...' error, while uv pip install works

[MohammedElHamraoui]

Summary

mkdir uv-add-test-project
cd uv-add-test-project
uv venv .venv
source .venv/bin/activate
echo "fastapi[standard]" > requirements.txt # Minimal example
uv add -r requirements.txt # Fails with error
uv add fastapi[standard] # Fails with error
uv pip install -r requirements.txt # Works correctly
uv pip install fastapi[standard] # Works correctly

$ uv -v add -r requirements.txt
DEBUG uv 0.6.3
error: No pyproject.toml found in current directory or any parent directory

$ uv -v add fastapi[standard]
DEBUG uv 0.6.3
error: No pyproject.toml found in current directory or any parent directory

Platform

Linux Fedora 6.13.4-200.fc41.x86_64 #1 SMP PREEMPT_DYNAMIC Sat Feb 22 16:09:10 UTC 2025 x86_64 GNU/Linux

Version

uv 0.6.3

Python version

CPython 3.13.2

[charliermarsh]

Can you expand on what's misleading here? This looks correct to me. You must have a pyproject.toml in order to use the Project APIs (uv sync, uv add, uv run, etc.).

[MohammedElHamraoui]

Thank you for the quick response and clarification! I understand now that uv add, uv run, and uv sync are designed as "Project APIs" and are intended to be used within the context of a project defined by pyproject.toml. That's helpful to know about the intended design.

However, from a user perspective, especially for those coming from venv/pip, the error message "No pyproject.toml found..." can still be misleading in the following scenarios:

1. Initial Expectation of uv add as a general package installer: Many users (like myself initially) might naturally assume that uv add is the primary command for adding packages in a virtual environment, intending it as a faster replacement for pip install for general use cases, especially given uv's focus on speed. The "Project API" distinction might not be immediately obvious.

2. uv add -r requirements.txt implies pip install -r equivalence: The -r requirements.txt flag is a standard idiom from pip for installing from requirements files, which users are very familiar with and expect to work without pyproject.toml. Seeing uv add -r requirements.txt and then getting a pyproject.toml error is unexpected because pip install -r works perfectly fine without it.

3. uv pip install works without pyproject.toml: The fact that uv pip install fastapi[standard] does work in the same virtual environment reinforces the confusion. It shows that uv can install packages in a venv without pyproject.toml, but uv add seemingly cannot, even for basic installation tasks. This creates an apparent inconsistency from a user's standpoint.

4. Error message directs user to the wrong solution (for basic installation): The error message strongly suggests creating a pyproject.toml file. However, for users who simply want to install packages into a virtual environment (e.g., for a quick script, tutorial, or simple project not yet structured with pyproject.toml), creating a pyproject.toml is an unnecessary step. They are looking for a way to just install packages, not necessarily to define a full project build system at that moment. It makes the user think they are doing something fundamentally wrong or missing a crucial project configuration file for a basic installation task.

Suggestion for improvement (optional):

Perhaps the error message for uv add (and related Project APIs) could be made more explicit about the intended use case and the pyproject.toml requirement. For example, instead of "No pyproject.toml found...", a more informative message might be something like:

"Error: uv add is intended for use within Python projects defined by pyproject.toml. To use uv add, please ensure you are in a project directory containing a pyproject.toml file that defines your project's dependencies and build system. For basic package installation in a virtual environment without a pyproject.toml-defined project, use uv pip install <package_name> or uv pip install -r requirements.txt instead."

Or, if uv add is always intended to require pyproject.toml, even for installing from requirements.txt, then clarifying this in the documentation and perhaps in the error message itself would be very helpful to avoid user confusion and set the right expectations.

Thank you again for clarifying the intended behavior. I appreciate the fast response!

[charliermarsh]

Seems reasonable to make this error clearer and more actionable.

[leelasaivoonna]

@MohammedElHamraoui Well said, in docs they could have mentioned it clearly,

But those commands works in Powershell without issues, you must have ran it in command prompt

[Deejaythenobody]

im having this issue running uv sync after creating the env.