Python
/
uv
mirror of https://github.com/astral-sh/uv
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve the CLI help for options that accept requirements files (#15706)

This commit is contained in:
Zanie Blue 2025-09-08 08:23:52 -05:00 committed by GitHub
parent 4de559d70d
commit 5f8c7181b9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 48 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
crates/uv-cli/src/lib.rs
View File

@ -1192,7 +1192,10 @@ fn parse_maybe_string(input: &str) -> Result<Maybe<String>, String> {
#[derive(Args)]
#[command(group = clap::ArgGroup::new("sources").required(true).multiple(true))]
pub struct PipCompileArgs {
/// Include all packages listed in the given `requirements.in` files.
/// Include the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// `pylock.toml`, `pyproject.toml`, `setup.py`, and `setup.cfg`.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will extract the
/// requirements for the relevant project.
@ -1544,7 +1547,10 @@ pub struct PipCompileArgs {
#[derive(Args)]
pub struct PipSyncArgs {
/// Include all packages listed in the given `requirements.txt` files.
/// Include the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// `pylock.toml`, `pyproject.toml`, `setup.py`, and `setup.cfg`.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
/// extract the requirements for the relevant project.
@ -1836,7 +1842,10 @@ pub struct PipInstallArgs {
#[arg(group = "sources")]
pub package: Vec<String>,
/// Install all packages listed in the given `requirements.txt`, PEP 723 scripts, or `pylock.toml` files.
/// Install the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// `pylock.toml`, `pyproject.toml`, `setup.py`, and `setup.cfg`.
///
/// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will extract the
/// requirements for the relevant project.
@ -2155,7 +2164,10 @@ pub struct PipUninstallArgs {
#[arg(group = "sources")]
pub package: Vec<String>,
/// Uninstall all packages listed in the given requirements files.
/// Uninstall the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// `pylock.toml`, `pyproject.toml`, `setup.py`, and `setup.cfg`.
#[arg(long, short, alias = "requirement", group = "sources", value_parser = parse_file_path)]
pub requirements: Vec<PathBuf>,
@ -3210,8 +3222,10 @@ pub struct RunArgs {
#[arg(long)]
pub with_editable: Vec<comma::CommaSeparatedRequirements>,
/// Run with all packages listed in the given `requirements.txt` files or PEP 723 Python
/// scripts.
/// Run with the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// and `pylock.toml`.
///
/// The same environment semantics as `--with` apply.
///
@ -3735,7 +3749,10 @@ pub struct AddArgs {
#[arg(group = "sources")]
pub packages: Vec<String>,
/// Add all packages listed in the given `requirements.txt` files.
/// Add the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// `pylock.toml`, `pyproject.toml`, `setup.py`, and `setup.cfg`.
#[arg(long, short, alias = "requirement", group = "sources", value_parser = parse_file_path)]
pub requirements: Vec<PathBuf>,
@ -4591,8 +4608,10 @@ pub struct ToolRunArgs {
#[arg(long)]
pub with_editable: Vec<comma::CommaSeparatedRequirements>,
/// Run with all packages listed in the given `requirements.txt` files or PEP 723 Python
/// scripts.
/// Run with the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// and `pylock.toml`.
#[arg(long, value_delimiter = ',', value_parser = parse_maybe_file_path)]
pub with_requirements: Vec<Maybe<PathBuf>>,
@ -4722,8 +4741,10 @@ pub struct ToolInstallArgs {
#[arg(short = 'w', long)]
pub with: Vec<comma::CommaSeparatedRequirements>,
/// Run with all packages listed in the given `requirements.txt` files or PEP 723 Python
/// scripts.
/// Run with the packages listed in the given files.
///
/// The following formats are supported: `requirements.txt`, `.py` files with inline metadata,
/// and `pylock.toml`.
#[arg(long, value_delimiter = ',', value_parser = parse_maybe_file_path)]
pub with_requirements: Vec<Maybe<PathBuf>>,

24
docs/reference/cli.md
View File

@ -611,7 +611,8 @@ used.</p>
<p>When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.</p>
</dd><dt id="uv-run--with-editable"><a href="#uv-run--with-editable"><code>--with-editable</code></a> <i>with-editable</i></dt><dd><p>Run with the given packages installed in editable mode.</p>
<p>When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.</p>
</dd><dt id="uv-run--with-requirements"><a href="#uv-run--with-requirements"><code>--with-requirements</code></a> <i>with-requirements</i></dt><dd><p>Run with all packages listed in the given <code>requirements.txt</code> files or PEP 723 Python scripts.</p>
</dd><dt id="uv-run--with-requirements"><a href="#uv-run--with-requirements"><code>--with-requirements</code></a> <i>with-requirements</i></dt><dd><p>Run with the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, and <code>pylock.toml</code>.</p>
<p>The same environment semantics as <code>--with</code> apply.</p>
<p>Using <code>pyproject.toml</code>, <code>setup.py</code>, or <code>setup.cfg</code> files is not allowed.</p>
</dd></dl>
@ -941,7 +942,8 @@ uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
</dd><dt id="uv-add--refresh-package"><a href="#uv-add--refresh-package"><code>--refresh-package</code></a> <i>refresh-package</i></dt><dd><p>Refresh cached data for a specific package</p>
</dd><dt id="uv-add--reinstall"><a href="#uv-add--reinstall"><code>--reinstall</code></a>, <code>--force-reinstall</code></dt><dd><p>Reinstall all packages, regardless of whether they're already installed. Implies <code>--refresh</code></p>
</dd><dt id="uv-add--reinstall-package"><a href="#uv-add--reinstall-package"><code>--reinstall-package</code></a> <i>reinstall-package</i></dt><dd><p>Reinstall a specific package, regardless of whether it's already installed. Implies <code>--refresh-package</code></p>
</dd><dt id="uv-add--requirements"><a href="#uv-add--requirements"><code>--requirements</code></a>, <code>--requirement</code>, <code>-r</code> <i>requirements</i></dt><dd><p>Add all packages listed in the given <code>requirements.txt</code> files</p>
</dd><dt id="uv-add--requirements"><a href="#uv-add--requirements"><code>--requirements</code></a>, <code>--requirement</code>, <code>-r</code> <i>requirements</i></dt><dd><p>Add the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, <code>pylock.toml</code>, <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code>.</p>
</dd><dt id="uv-add--resolution"><a href="#uv-add--resolution"><code>--resolution</code></a> <i>resolution</i></dt><dd><p>The strategy to use when selecting between the different compatible versions for a given package requirement.</p>
<p>By default, uv will use the latest compatible version of each package (<code>highest</code>).</p>
<p>May also be set with the <code>UV_RESOLUTION</code> environment variable.</p><p>Possible values:</p>
@ -2546,7 +2548,8 @@ uv tool run [OPTIONS] [COMMAND]
</dd><dt id="uv-tool-run--with"><a href="#uv-tool-run--with"><code>--with</code></a>, <code>-w</code> <i>with</i></dt><dd><p>Run with the given packages installed</p>
</dd><dt id="uv-tool-run--with-editable"><a href="#uv-tool-run--with-editable"><code>--with-editable</code></a> <i>with-editable</i></dt><dd><p>Run with the given packages installed in editable mode</p>
<p>When used in a project, these dependencies will be layered on top of the uv tool's environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.</p>
</dd><dt id="uv-tool-run--with-requirements"><a href="#uv-tool-run--with-requirements"><code>--with-requirements</code></a> <i>with-requirements</i></dt><dd><p>Run with all packages listed in the given <code>requirements.txt</code> files or PEP 723 Python scripts</p>
</dd><dt id="uv-tool-run--with-requirements"><a href="#uv-tool-run--with-requirements"><code>--with-requirements</code></a> <i>with-requirements</i></dt><dd><p>Run with the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, and <code>pylock.toml</code>.</p>
</dd></dl>
### uv tool install
@ -2773,7 +2776,8 @@ uv tool install [OPTIONS] <PACKAGE>
</dd><dt id="uv-tool-install--with"><a href="#uv-tool-install--with"><code>--with</code></a>, <code>-w</code> <i>with</i></dt><dd><p>Include the following additional requirements</p>
</dd><dt id="uv-tool-install--with-editable"><a href="#uv-tool-install--with-editable"><code>--with-editable</code></a> <i>with-editable</i></dt><dd><p>Include the given packages in editable mode</p>
</dd><dt id="uv-tool-install--with-executables-from"><a href="#uv-tool-install--with-executables-from"><code>--with-executables-from</code></a> <i>with-executables-from</i></dt><dd><p>Install executables from the following packages</p>
</dd><dt id="uv-tool-install--with-requirements"><a href="#uv-tool-install--with-requirements"><code>--with-requirements</code></a> <i>with-requirements</i></dt><dd><p>Run with all packages listed in the given <code>requirements.txt</code> files or PEP 723 Python scripts</p>
</dd><dt id="uv-tool-install--with-requirements"><a href="#uv-tool-install--with-requirements"><code>--with-requirements</code></a> <i>with-requirements</i></dt><dd><p>Run with the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, and <code>pylock.toml</code>.</p>
</dd></dl>
### uv tool upgrade
@ -3988,7 +3992,8 @@ uv pip compile [OPTIONS] <SRC_FILE|--group <GROUP>>
<h3 class="cli-reference">Arguments</h3>
<dl class="cli-reference"><dt id="uv-pip-compile--src_file"><a href="#uv-pip-compile--src_file"<code>SRC_FILE</code></a></dt><dd><p>Include all packages listed in the given <code>requirements.in</code> files.</p>
<dl class="cli-reference"><dt id="uv-pip-compile--src_file"><a href="#uv-pip-compile--src_file"<code>SRC_FILE</code></a></dt><dd><p>Include the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, <code>pylock.toml</code>, <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code>.</p>
<p>If a <code>pyproject.toml</code>, <code>setup.py</code>, or <code>setup.cfg</code> file is provided, uv will extract the requirements for the relevant project.</p>
<p>If <code>-</code> is provided, then requirements will be read from stdin.</p>
<p>The order of the requirements files and the requirements in them is used to determine priority during resolution.</p>
@ -4311,7 +4316,8 @@ uv pip sync [OPTIONS] <SRC_FILE>...
<h3 class="cli-reference">Arguments</h3>
<dl class="cli-reference"><dt id="uv-pip-sync--src_file"><a href="#uv-pip-sync--src_file"<code>SRC_FILE</code></a></dt><dd><p>Include all packages listed in the given <code>requirements.txt</code> files.</p>
<dl class="cli-reference"><dt id="uv-pip-sync--src_file"><a href="#uv-pip-sync--src_file"<code>SRC_FILE</code></a></dt><dd><p>Include the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, <code>pylock.toml</code>, <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code>.</p>
<p>If a <code>pyproject.toml</code>, <code>setup.py</code>, or <code>setup.cfg</code> file is provided, uv will extract the requirements for the relevant project.</p>
<p>If <code>-</code> is provided, then requirements will be read from stdin.</p>
</dd></dl>
@ -4808,7 +4814,8 @@ should be used with caution, as it can modify the system Python installation.</p
<ul>
<li>Git dependencies are not supported. - Editable installations are not supported. - Local dependencies are not supported, unless they point to a specific wheel (<code>.whl</code>) or source archive (<code>.zip</code>, <code>.tar.gz</code>), as opposed to a directory.</li>
</ul>
<p>May also be set with the <code>UV_REQUIRE_HASHES</code> environment variable.</p></dd><dt id="uv-pip-install--requirements"><a href="#uv-pip-install--requirements"><code>--requirements</code></a>, <code>--requirement</code>, <code>-r</code> <i>requirements</i></dt><dd><p>Install all packages listed in the given <code>requirements.txt</code>, PEP 723 scripts, or <code>pylock.toml</code> files.</p>
<p>May also be set with the <code>UV_REQUIRE_HASHES</code> environment variable.</p></dd><dt id="uv-pip-install--requirements"><a href="#uv-pip-install--requirements"><code>--requirements</code></a>, <code>--requirement</code>, <code>-r</code> <i>requirements</i></dt><dd><p>Install the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, <code>pylock.toml</code>, <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code>.</p>
<p>If a <code>pyproject.toml</code>, <code>setup.py</code>, or <code>setup.cfg</code> file is provided, uv will extract the requirements for the relevant project.</p>
<p>If <code>-</code> is provided, then requirements will be read from stdin.</p>
</dd><dt id="uv-pip-install--resolution"><a href="#uv-pip-install--resolution"><code>--resolution</code></a> <i>resolution</i></dt><dd><p>The strategy to use when selecting between the different compatible versions for a given package requirement.</p>
@ -4955,7 +4962,8 @@ should be used with caution, as it can modify the system Python installation.</p
<p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
<p>May also be set with the <code>UV_PYTHON</code> environment variable.</p></dd><dt id="uv-pip-uninstall--quiet"><a href="#uv-pip-uninstall--quiet"><code>--quiet</code></a>, <code>-q</code></dt><dd><p>Use quiet output.</p>
<p>Repeating this option, e.g., <code>-qq</code>, will enable a silent mode in which uv will write no output to stdout.</p>
</dd><dt id="uv-pip-uninstall--requirements"><a href="#uv-pip-uninstall--requirements"><code>--requirements</code></a>, <code>--requirement</code>, <code>-r</code> <i>requirements</i></dt><dd><p>Uninstall all packages listed in the given requirements files</p>
</dd><dt id="uv-pip-uninstall--requirements"><a href="#uv-pip-uninstall--requirements"><code>--requirements</code></a>, <code>--requirement</code>, <code>-r</code> <i>requirements</i></dt><dd><p>Uninstall the packages listed in the given files.</p>
<p>The following formats are supported: <code>requirements.txt</code>, <code>.py</code> files with inline metadata, <code>pylock.toml</code>, <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code>.</p>
</dd><dt id="uv-pip-uninstall--system"><a href="#uv-pip-uninstall--system"><code>--system</code></a></dt><dd><p>Use the system Python to uninstall packages.</p>
<p>By default, uv uninstalls from the virtual environment in the current working directory or any parent directory. The <code>--system</code> option instructs uv to instead use the first Python found in the system <code>PATH</code>.</p>
<p>WARNING: <code>--system</code> is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>