Add uv tool install (#4492)

This is the minimal "working" implementation. In summary, we:

- Resolve the requested requirements
- Create an environment at `$UV_STATE_DIR/tools/$name`
- Inspect the `dist-info` for the main requirement to determine its
entry points scripts
- Link the entry points from a user-executable directory
(`$XDG_BIN_HOME`) to the environment bin
- Create an entry at `$UV_STATE_DIR/tools/tools.toml` tracking the
user's request

The idea with `tools.toml` is that it allows us to perform upgrades and
syncs, retaining the original user request (similar to declarations in a
`pyproject.toml`). I imagine using a similar schema in the
`pyproject.toml` in the future if/when we add project-levle tools. I'm
also considering exposing `tools.toml` in the standard uv configuration
directory instead of the state directory, but it seems nice to tuck it
away for now while we iterate on it. Installing a tool won't perform a
sync of other tool environments, we'll probably have an explicit `uv
tool sync` command for that?

I've split out todos into follow-up pull requests:

- #4509 (failing on Windows)
- #4501 
- #4504 

Closes #4485

Cargo.toml

@@ -45,6 +45,7 @@ uv-requirements = { path = "crates/uv-requirements" }
 uv-resolver = { path = "crates/uv-resolver" }
 uv-settings = { path = "crates/uv-settings" }
 uv-state = { path = "crates/uv-state" }
+uv-tool = { path = "crates/uv-tool" }
 uv-toolchain = { path = "crates/uv-toolchain" }
 uv-types = { path = "crates/uv-types" }
 uv-version = { path = "crates/uv-version" }

crates/install-wheel-rs/src/lib.rs

@@ -11,9 +11,11 @@ use zip::result::ZipError;
 use pep440_rs::Version;
 use platform_tags::{Arch, Os};
 use pypi_types::Scheme;
+pub use script::{scripts_from_ini, Script};
 pub use uninstall::{uninstall_egg, uninstall_legacy_editable, uninstall_wheel, Uninstall};
 use uv_fs::Simplified;
 use uv_normalize::PackageName;
+pub use wheel::{parse_wheel_file, LibKind};
 
 pub mod linker;
 pub mod metadata;

crates/install-wheel-rs/src/linker.rs

@@ -1,7 +1,7 @@
 //! Like `wheel.rs`, but for installing wheels that have already been unzipped, rather than
 //! reading from a zip file.
 
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::str::FromStr;
 use std::time::SystemTime;
 
@@ -143,6 +143,24 @@ pub fn install_wheel(
     Ok(())
 }
 
+/// Determine the absolute path to an entrypoint script.
+pub fn entrypoint_path(entrypoint: &Script, layout: &Layout) -> PathBuf {
+    if cfg!(windows) {
+        // On windows we actually build an .exe wrapper
+        let script_name = entrypoint
+            .name
+            // FIXME: What are the in-reality rules here for names?
+            .strip_suffix(".py")
+            .unwrap_or(&entrypoint.name)
+            .to_string()
+            + ".exe";
+
+        layout.scheme.scripts.join(script_name)
+    } else {
+        layout.scheme.scripts.join(&entrypoint.name)
+    }
+}
+
 /// Find the `dist-info` directory in an unzipped wheel.
 ///
 /// See: <https://github.com/PyO3/python-pkginfo-rs>

crates/install-wheel-rs/src/script.rs

@@ -9,10 +9,10 @@ use crate::{wheel, Error};
 /// A script defining the name of the runnable entrypoint and the module and function that should be
 /// run.
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
-pub(crate) struct Script {
-    pub(crate) name: String,
-    pub(crate) module: String,
-    pub(crate) function: String,
+pub struct Script {
+    pub name: String,
+    pub module: String,
+    pub function: String,
 }
 
 impl Script {
@@ -64,7 +64,7 @@ impl Script {
     }
 }
 
-pub(crate) fn scripts_from_ini(
+pub fn scripts_from_ini(
     extras: Option<&[String]>,
     python_minor: u8,
     ini: String,

crates/install-wheel-rs/src/wheel.rs

@@ -17,6 +17,7 @@ use zip::ZipWriter;
 use pypi_types::DirectUrl;
 use uv_fs::{relative_to, Simplified};
 
+use crate::linker::entrypoint_path;
 use crate::record::RecordEntry;
 use crate::script::Script;
 use crate::{Error, Layout};
@@ -255,20 +256,7 @@ pub(crate) fn write_script_entrypoints(
     is_gui: bool,
 ) -> Result<(), Error> {
     for entrypoint in entrypoints {
-        let entrypoint_absolute = if cfg!(windows) {
-            // On windows we actually build an .exe wrapper
-            let script_name = entrypoint
-                .name
-                // FIXME: What are the in-reality rules here for names?
-                .strip_suffix(".py")
-                .unwrap_or(&entrypoint.name)
-                .to_string()
-                + ".exe";
-
-            layout.scheme.scripts.join(script_name)
-        } else {
-            layout.scheme.scripts.join(&entrypoint.name)
-        };
+        let entrypoint_absolute = entrypoint_path(entrypoint, layout);
 
         let entrypoint_relative = pathdiff::diff_paths(&entrypoint_absolute, site_packages)
             .ok_or_else(|| {
@@ -320,7 +308,7 @@ pub(crate) fn write_script_entrypoints(
 
 /// Whether the wheel should be installed into the `purelib` or `platlib` directory.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub(crate) enum LibKind {
+pub enum LibKind {
     /// Install into the `purelib` directory.
     Pure,
     /// Install into the `platlib` directory.
@@ -331,7 +319,7 @@ pub(crate) enum LibKind {
 ///
 /// > {distribution}-{version}.dist-info/WHEEL is metadata about the archive itself in the same
 /// > basic key: value format:
-pub(crate) fn parse_wheel_file(wheel_text: &str) -> Result<LibKind, Error> {
+pub fn parse_wheel_file(wheel_text: &str) -> Result<LibKind, Error> {
     // {distribution}-{version}.dist-info/WHEEL is metadata about the archive itself in the same basic key: value format:
     let data = parse_key_value_file(&mut wheel_text.as_bytes(), "WHEEL")?;
 

crates/uv-cli/src/lib.rs

@@ -1838,6 +1838,8 @@ pub struct ToolNamespace {
 pub enum ToolCommand {
     /// Run a tool
     Run(ToolRunArgs),
+    /// Install a tool
+    Install(ToolInstallArgs),
 }
 
 #[derive(Args)]
@@ -1881,6 +1883,46 @@ pub struct ToolRunArgs {
     pub python: Option<String>,
 }
 
+#[derive(Args)]
+#[allow(clippy::struct_excessive_bools)]
+pub struct ToolInstallArgs {
+    /// The command to install.
+    pub name: String,
+
+    /// Use the given package to provide the command.
+    ///
+    /// By default, the package name is assumed to match the command name.
+    #[arg(long)]
+    pub from: Option<String>,
+
+    /// Include the following extra requirements.
+    #[arg(long)]
+    pub with: Vec<String>,
+
+    #[command(flatten)]
+    pub installer: ResolverInstallerArgs,
+
+    #[command(flatten)]
+    pub build: BuildArgs,
+
+    #[command(flatten)]
+    pub refresh: RefreshArgs,
+
+    /// The Python interpreter to use to build the tool environment.
+    ///
+    /// By default, uv will search for a Python executable in the `PATH`. uv ignores virtual
+    /// environments while looking for interpreter for tools. The `--python` option allows
+    /// you to specify a different interpreter.
+    ///
+    /// Supported formats:
+    /// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or
+    ///   `python3.10` on Linux and macOS.
+    /// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`.
+    /// - `/home/ferris/.local/bin/python3.10` uses the exact Python at the given path.
+    #[arg(long, short, env = "UV_PYTHON", verbatim_doc_comment)]
+    pub python: Option<String>,
+}
+
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct ToolchainNamespace {

crates/uv-state/src/lib.rs

@@ -95,14 +95,17 @@ impl StateStore {
 /// are subdirectories of the state store root.
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum StateBucket {
-    // Managed toolchain
+    // Managed toolchains
     Toolchains,
+    // Installed tools
+    Tools,
 }
 
 impl StateBucket {
     fn to_str(self) -> &'static str {
         match self {
             Self::Toolchains => "toolchains",
+            Self::Tools => "tools",
         }
     }
 }

crates/uv-tool/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "uv-tool"
+version = "0.0.1"
+edition = { workspace = true }
+rust-version = { workspace = true }
+homepage = { workspace = true }
+documentation = { workspace = true }
+repository = { workspace = true }
+authors = { workspace = true }
+license = { workspace = true }
+
+[lints]
+workspace = true
+
+[dependencies]
+uv-fs = { workspace = true }
+uv-state = { workspace = true }
+pep508_rs = { workspace = true }
+pypi-types = { workspace = true }
+uv-virtualenv = { workspace = true }
+uv-toolchain = { workspace = true }
+install-wheel-rs = { workspace = true }
+pep440_rs = { workspace = true }
+
+thiserror = { workspace = true }
+tracing = { workspace = true }
+fs-err = { workspace = true }
+serde = { workspace = true }
+toml = { workspace = true } 
+toml_edit = { workspace = true } 
+dirs-sys = { workspace = true }