mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-07 13:25:00 +00:00
Generate environment variables doc from code (#8493)
## Summary Resolves #8417 I've just begun learning procedural macros, so this PR is more of a proof of concept. It's still a work in progress, and I welcome any assistance or feedback.
This commit is contained in:
Jo
GitHub
parent
545a55f58f
commit
3dfedf1fef
13 changed files with 491 additions and 135 deletions
|
|
@ -3,5 +3,6 @@ CHANGELOG.md
|
|||
PREVIEW-CHANGELOG.md
|
||||
docs/reference/cli.md
|
||||
docs/reference/settings.md
|
||||
docs/configuration/environment.md
|
||||
ecosystem/home-assistant-core/LICENSE.md
|
||||
docs/guides/integration/gitlab.md
|
||||
|
|
|
|||
3
Cargo.lock
generated
3
Cargo.lock
generated
|
|
@ -5264,6 +5264,9 @@ dependencies = [
|
|||
[[package]]
|
||||
name = "uv-static"
|
||||
version = "0.0.1"
|
||||
dependencies = [
|
||||
"uv-macros",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "uv-tool"
|
||||
|
|
|
|||
|
|
@ -2,7 +2,10 @@
|
|||
|
||||
use anyhow::Result;
|
||||
|
||||
use crate::{generate_cli_reference, generate_json_schema, generate_options_reference};
|
||||
use crate::{
|
||||
generate_cli_reference, generate_env_vars_reference, generate_json_schema,
|
||||
generate_options_reference,
|
||||
};
|
||||
|
||||
#[derive(clap::Args)]
|
||||
pub(crate) struct Args {
|
||||
|
|
@ -27,5 +30,6 @@ pub(crate) fn main(args: &Args) -> Result<()> {
|
|||
generate_json_schema::main(&generate_json_schema::Args { mode: args.mode })?;
|
||||
generate_options_reference::main(&generate_options_reference::Args { mode: args.mode })?;
|
||||
generate_cli_reference::main(&generate_cli_reference::Args { mode: args.mode })?;
|
||||
generate_env_vars_reference::main(&generate_env_vars_reference::Args { mode: args.mode })?;
|
||||
Ok(())
|
||||
}
|
||||
|
|
|
|||
|
|
@ -31,7 +31,6 @@ const SHOW_HIDDEN_COMMANDS: &[&str] = &["generate-shell-completion"];
|
|||
|
||||
#[derive(clap::Args)]
|
||||
pub(crate) struct Args {
|
||||
/// Write the generated output to stdout (rather than to `settings.md`).
|
||||
#[arg(long, default_value_t, value_enum)]
|
||||
pub(crate) mode: Mode,
|
||||
}
|
||||
|
|
|
|||
98
crates/uv-dev/src/generate_env_vars_reference.rs
Normal file
98
crates/uv-dev/src/generate_env_vars_reference.rs
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
//! Generate the environment variables reference from `uv_static::EnvVars`.
|
||||
|
||||
use anyhow::bail;
|
||||
use pretty_assertions::StrComparison;
|
||||
use std::path::PathBuf;
|
||||
|
||||
use uv_static::EnvVars;
|
||||
|
||||
use crate::generate_all::Mode;
|
||||
use crate::ROOT_DIR;
|
||||
|
||||
#[derive(clap::Args)]
|
||||
pub(crate) struct Args {
|
||||
#[arg(long, default_value_t, value_enum)]
|
||||
pub(crate) mode: Mode,
|
||||
}
|
||||
|
||||
pub(crate) fn main(args: &Args) -> anyhow::Result<()> {
|
||||
let reference_string = generate();
|
||||
let filename = "environment.md";
|
||||
let reference_path = PathBuf::from(ROOT_DIR)
|
||||
.join("docs")
|
||||
.join("configuration")
|
||||
.join(filename);
|
||||
|
||||
match args.mode {
|
||||
Mode::DryRun => {
|
||||
anstream::println!("{reference_string}");
|
||||
}
|
||||
Mode::Check => match fs_err::read_to_string(reference_path) {
|
||||
Ok(current) => {
|
||||
if current == reference_string {
|
||||
anstream::println!("Up-to-date: {filename}");
|
||||
} else {
|
||||
let comparison = StrComparison::new(¤t, &reference_string);
|
||||
bail!("{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{comparison}");
|
||||
}
|
||||
}
|
||||
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
|
||||
bail!("{filename} not found, please run `cargo dev generate-env-vars-reference`");
|
||||
}
|
||||
Err(err) => {
|
||||
bail!(
|
||||
"{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{err}"
|
||||
);
|
||||
}
|
||||
},
|
||||
Mode::Write => match fs_err::read_to_string(&reference_path) {
|
||||
Ok(current) => {
|
||||
if current == reference_string {
|
||||
anstream::println!("Up-to-date: {filename}");
|
||||
} else {
|
||||
anstream::println!("Updating: {filename}");
|
||||
fs_err::write(reference_path, reference_string.as_bytes())?;
|
||||
}
|
||||
}
|
||||
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
|
||||
anstream::println!("Updating: {filename}");
|
||||
fs_err::write(reference_path, reference_string.as_bytes())?;
|
||||
}
|
||||
Err(err) => {
|
||||
bail!("{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{err}");
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn generate() -> String {
|
||||
let mut output = String::new();
|
||||
|
||||
output.push_str("# Environment variables\n\n");
|
||||
output.push_str("uv respects the following environment variables:\n\n");
|
||||
|
||||
for (var, doc) in EnvVars::metadata() {
|
||||
// Remove empty lines and ddd two spaces to the beginning from the second line.
|
||||
let doc = doc
|
||||
.lines()
|
||||
.enumerate()
|
||||
.filter(|(_, line)| !line.trim().is_empty())
|
||||
.map(|(i, line)| {
|
||||
if i == 0 {
|
||||
line.to_string()
|
||||
} else {
|
||||
format!(" {line}")
|
||||
}
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n");
|
||||
output.push_str(&format!("- `{var}`: {doc}\n"));
|
||||
}
|
||||
|
||||
output
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests;
|
||||
19
crates/uv-dev/src/generate_env_vars_reference/tests.rs
Normal file
19
crates/uv-dev/src/generate_env_vars_reference/tests.rs
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
use std::env;
|
||||
|
||||
use anyhow::Result;
|
||||
|
||||
use uv_static::EnvVars;
|
||||
|
||||
use crate::generate_all::Mode;
|
||||
|
||||
use super::{main, Args};
|
||||
|
||||
#[test]
|
||||
fn test_generate_env_vars_reference() -> Result<()> {
|
||||
let mode = if env::var(EnvVars::UV_UPDATE_SCHEMA).as_deref() == Ok("1") {
|
||||
Mode::Write
|
||||
} else {
|
||||
Mode::Check
|
||||
};
|
||||
main(&Args { mode })
|
||||
}
|
||||
|
|
@ -27,7 +27,6 @@ struct CombinedOptions {
|
|||
|
||||
#[derive(clap::Args)]
|
||||
pub(crate) struct Args {
|
||||
/// Write the generated output to stdout (rather than to `uv.schema.json`).
|
||||
#[arg(long, default_value_t, value_enum)]
|
||||
pub(crate) mode: Mode,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -34,7 +34,6 @@ struct CombinedOptions {
|
|||
|
||||
#[derive(clap::Args)]
|
||||
pub(crate) struct Args {
|
||||
/// Write the generated output to stdout (rather than to `settings.md`).
|
||||
#[arg(long, default_value_t, value_enum)]
|
||||
pub(crate) mode: Mode,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@ use crate::clear_compile::ClearCompileArgs;
|
|||
use crate::compile::CompileArgs;
|
||||
use crate::generate_all::Args as GenerateAllArgs;
|
||||
use crate::generate_cli_reference::Args as GenerateCliReferenceArgs;
|
||||
use crate::generate_env_vars_reference::Args as GenerateEnvVarsReferenceArgs;
|
||||
use crate::generate_json_schema::Args as GenerateJsonSchemaArgs;
|
||||
use crate::generate_options_reference::Args as GenerateOptionsReferenceArgs;
|
||||
#[cfg(feature = "render")]
|
||||
|
|
@ -31,6 +32,7 @@ mod clear_compile;
|
|||
mod compile;
|
||||
mod generate_all;
|
||||
mod generate_cli_reference;
|
||||
mod generate_env_vars_reference;
|
||||
mod generate_json_schema;
|
||||
mod generate_options_reference;
|
||||
mod render_benchmarks;
|
||||
|
|
@ -54,6 +56,8 @@ enum Cli {
|
|||
GenerateOptionsReference(GenerateOptionsReferenceArgs),
|
||||
/// Generate the CLI reference for the documentation.
|
||||
GenerateCliReference(GenerateCliReferenceArgs),
|
||||
/// Generate the environment variables reference for the documentation.
|
||||
GenerateEnvVarsReference(GenerateEnvVarsReferenceArgs),
|
||||
#[cfg(feature = "render")]
|
||||
/// Render the benchmarks.
|
||||
RenderBenchmarks(RenderBenchmarksArgs),
|
||||
|
|
@ -70,6 +74,7 @@ async fn run() -> Result<()> {
|
|||
Cli::GenerateJSONSchema(args) => generate_json_schema::main(&args)?,
|
||||
Cli::GenerateOptionsReference(args) => generate_options_reference::main(&args)?,
|
||||
Cli::GenerateCliReference(args) => generate_cli_reference::main(&args)?,
|
||||
Cli::GenerateEnvVarsReference(args) => generate_env_vars_reference::main(&args)?,
|
||||
#[cfg(feature = "render")]
|
||||
Cli::RenderBenchmarks(args) => render_benchmarks::render_benchmarks(&args)?,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ mod options_metadata;
|
|||
|
||||
use proc_macro::TokenStream;
|
||||
use quote::quote;
|
||||
use syn::{parse_macro_input, DeriveInput};
|
||||
use syn::{parse_macro_input, Attribute, DeriveInput, ImplItem, ItemImpl, LitStr};
|
||||
|
||||
#[proc_macro_derive(OptionsMetadata, attributes(option, doc, option_group))]
|
||||
pub fn derive_options_metadata(input: TokenStream) -> TokenStream {
|
||||
|
|
@ -49,3 +49,92 @@ fn impl_combine(ast: &DeriveInput) -> TokenStream {
|
|||
};
|
||||
gen.into()
|
||||
}
|
||||
|
||||
fn get_doc_comment(attrs: &[Attribute]) -> String {
|
||||
attrs
|
||||
.iter()
|
||||
.filter_map(|attr| {
|
||||
if attr.path().is_ident("doc") {
|
||||
if let syn::Meta::NameValue(meta) = &attr.meta {
|
||||
if let syn::Expr::Lit(expr) = &meta.value {
|
||||
if let syn::Lit::Str(str) = &expr.lit {
|
||||
return Some(str.value().trim().to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
})
|
||||
.collect::<Vec<_>>()
|
||||
.join("\n")
|
||||
}
|
||||
|
||||
fn get_env_var_pattern_from_attr(attrs: &[Attribute]) -> Option<String> {
|
||||
attrs
|
||||
.iter()
|
||||
.find(|attr| attr.path().is_ident("attr_env_var_pattern"))
|
||||
.and_then(|attr| attr.parse_args::<LitStr>().ok())
|
||||
.map(|lit_str| lit_str.value())
|
||||
}
|
||||
|
||||
fn is_hidden(attrs: &[Attribute]) -> bool {
|
||||
attrs.iter().any(|attr| attr.path().is_ident("attr_hidden"))
|
||||
}
|
||||
|
||||
/// This attribute is used to generate environment variables metadata for [`uv_static::EnvVars`].
|
||||
#[proc_macro_attribute]
|
||||
pub fn attribute_env_vars_metadata(_attr: TokenStream, input: TokenStream) -> TokenStream {
|
||||
let ast = parse_macro_input!(input as ItemImpl);
|
||||
|
||||
let constants: Vec<_> = ast
|
||||
.items
|
||||
.iter()
|
||||
.filter_map(|item| match item {
|
||||
ImplItem::Const(item) if !is_hidden(&item.attrs) => {
|
||||
let name = item.ident.to_string();
|
||||
let doc = get_doc_comment(&item.attrs);
|
||||
Some((name, doc))
|
||||
}
|
||||
ImplItem::Fn(item) if !is_hidden(&item.attrs) => {
|
||||
// Extract the environment variable patterns.
|
||||
if let Some(pattern) = get_env_var_pattern_from_attr(&item.attrs) {
|
||||
let doc = get_doc_comment(&item.attrs);
|
||||
Some((pattern, doc))
|
||||
} else {
|
||||
None // Skip if pattern extraction fails.
|
||||
}
|
||||
}
|
||||
_ => None,
|
||||
})
|
||||
.collect();
|
||||
|
||||
let struct_name = &ast.self_ty;
|
||||
let pairs = constants.iter().map(|(name, doc)| {
|
||||
quote! {
|
||||
(#name, #doc)
|
||||
}
|
||||
});
|
||||
|
||||
let expanded = quote! {
|
||||
#ast
|
||||
|
||||
impl #struct_name {
|
||||
/// Returns a list of pairs of env var and their documentation defined in this impl block.
|
||||
pub fn metadata<'a>() -> &'a [(&'static str, &'static str)] {
|
||||
&[#(#pairs),*]
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
expanded.into()
|
||||
}
|
||||
|
||||
#[proc_macro_attribute]
|
||||
pub fn attr_hidden(_attr: TokenStream, item: TokenStream) -> TokenStream {
|
||||
item
|
||||
}
|
||||
|
||||
#[proc_macro_attribute]
|
||||
pub fn attr_env_var_pattern(_attr: TokenStream, item: TokenStream) -> TokenStream {
|
||||
item
|
||||
}
|
||||
|
|
|
|||
|
|
@ -16,3 +16,4 @@ doctest = false
|
|||
workspace = true
|
||||
|
||||
[dependencies]
|
||||
uv-macros = { workspace = true }
|
||||
|
|
|
|||
|
|
@ -1,117 +1,164 @@
|
|||
use uv_macros::{attr_env_var_pattern, attr_hidden, attribute_env_vars_metadata};
|
||||
|
||||
/// Declares all environment variable used throughout `uv` and its crates.
|
||||
pub struct EnvVars;
|
||||
|
||||
#[attribute_env_vars_metadata]
|
||||
impl EnvVars {
|
||||
/// Equivalent to the `--default-index` argument. Base index URL for searching packages.
|
||||
/// Equivalent to the `--default-index` command-line argument. If set, uv will use
|
||||
/// this URL as the default index when searching for packages.
|
||||
pub const UV_DEFAULT_INDEX: &'static str = "UV_DEFAULT_INDEX";
|
||||
|
||||
/// Equivalent to the `--index` argument. Additional indexes for searching packages.
|
||||
/// Equivalent to the `--index` command-line argument. If set, uv will use this
|
||||
/// space-separated list of URLs as additional indexes when searching for packages.
|
||||
pub const UV_INDEX: &'static str = "UV_INDEX";
|
||||
|
||||
/// Equivalent to the `--index-url` argument. Base index URL for searching packages.
|
||||
///
|
||||
/// Deprecated: use `UV_DEFAULT_INDEX` instead.
|
||||
/// Equivalent to the `--index-url` command-line argument. If set, uv will use this
|
||||
/// URL as the default index when searching for packages.
|
||||
/// (Deprecated: use `UV_DEFAULT_INDEX` instead.)
|
||||
pub const UV_INDEX_URL: &'static str = "UV_INDEX_URL";
|
||||
|
||||
/// Equivalent to the `--extra-index-url` argument. Additional indexes for searching packages.
|
||||
///
|
||||
/// Deprecated: use `UV_INDEX` instead.
|
||||
/// Equivalent to the `--extra-index-url` command-line argument. If set, uv will
|
||||
/// use this space-separated list of URLs as additional indexes when searching for packages.
|
||||
/// (Deprecated: use `UV_INDEX` instead.)
|
||||
pub const UV_EXTRA_INDEX_URL: &'static str = "UV_EXTRA_INDEX_URL";
|
||||
|
||||
/// Equivalent to the `--find-links` argument. Additional package search locations.
|
||||
/// Equivalent to the `--find-links` command-line argument. If set, uv will use this
|
||||
/// comma-separated list of additional locations to search for packages.
|
||||
pub const UV_FIND_LINKS: &'static str = "UV_FIND_LINKS";
|
||||
|
||||
/// Equivalent to the `--cache-dir` argument. Custom directory for caching.
|
||||
/// Equivalent to the `--cache-dir` command-line argument. If set, uv will use this
|
||||
/// directory for caching instead of the default cache directory.
|
||||
pub const UV_CACHE_DIR: &'static str = "UV_CACHE_DIR";
|
||||
|
||||
/// Equivalent to the `--no-cache` argument. Disables cache usage.
|
||||
/// Equivalent to the `--no-cache` command-line argument. If set, uv will not use the
|
||||
/// cache for any operations.
|
||||
pub const UV_NO_CACHE: &'static str = "UV_NO_CACHE";
|
||||
|
||||
/// Equivalent to the `--resolution` argument. Controls dependency resolution strategy.
|
||||
/// Equivalent to the `--resolution` command-line argument. For example, if set to
|
||||
/// `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies.
|
||||
pub const UV_RESOLUTION: &'static str = "UV_RESOLUTION";
|
||||
|
||||
/// Equivalent to the `--prerelease` argument. Allows or disallows pre-release versions.
|
||||
/// Equivalent to the `--prerelease` command-line argument. For example, if set to
|
||||
/// `allow`, uv will allow pre-release versions for all dependencies.
|
||||
pub const UV_PRERELEASE: &'static str = "UV_PRERELEASE";
|
||||
|
||||
/// Equivalent to the `--system` argument. Use system Python interpreter.
|
||||
/// Equivalent to the `--system` command-line argument. If set to `true`, uv will
|
||||
/// use the first Python interpreter found in the system `PATH`.
|
||||
/// WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI)
|
||||
/// or containerized environments and should be used with caution, as modifying the system
|
||||
/// Python can lead to unexpected behavior.
|
||||
pub const UV_SYSTEM_PYTHON: &'static str = "UV_SYSTEM_PYTHON";
|
||||
|
||||
/// Equivalent to the `--python` argument. Path to a specific Python interpreter.
|
||||
/// Equivalent to the `--python` command-line argument. If set to a path, uv will use
|
||||
/// this Python interpreter for all operations.
|
||||
pub const UV_PYTHON: &'static str = "UV_PYTHON";
|
||||
|
||||
/// Equivalent to the `--break-system-packages` argument. Allows breaking system packages.
|
||||
/// Equivalent to the `--break-system-packages` command-line argument. If set to `true`,
|
||||
/// uv will allow the installation of packages that conflict with system-installed packages.
|
||||
/// WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
|
||||
/// (CI) or containerized environments and should be used with caution, as modifying the system
|
||||
/// Python can lead to unexpected behavior.
|
||||
pub const UV_BREAK_SYSTEM_PACKAGES: &'static str = "UV_BREAK_SYSTEM_PACKAGES";
|
||||
|
||||
/// Equivalent to the `--native-tls` argument. Uses system's trust store for TLS.
|
||||
/// Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will
|
||||
/// use the system's trust store instead of the bundled `webpki-roots` crate.
|
||||
pub const UV_NATIVE_TLS: &'static str = "UV_NATIVE_TLS";
|
||||
|
||||
/// Equivalent to the `--index-strategy` argument. Defines strategy for searching index URLs.
|
||||
/// Equivalent to the `--index-strategy` command-line argument. For example, if
|
||||
/// set to `unsafe-any-match`, uv will consider versions of a given package available across all index
|
||||
/// URLs, rather than limiting its search to the first index URL that contains the package.
|
||||
pub const UV_INDEX_STRATEGY: &'static str = "UV_INDEX_STRATEGY";
|
||||
|
||||
/// Equivalent to the `--require-hashes` argument. Requires hashes for all dependencies.
|
||||
/// Equivalent to the `--require-hashes` command-line argument. If set to `true`,
|
||||
/// uv will require that all dependencies have a hash specified in the requirements file.
|
||||
pub const UV_REQUIRE_HASHES: &'static str = "UV_REQUIRE_HASHES";
|
||||
|
||||
/// Equivalent to the `--constraint` argument. Path to constraints file.
|
||||
/// Equivalent to the `--constraint` command-line argument. If set, uv will use this
|
||||
/// file as the constraints file. Uses space-separated list of files.
|
||||
pub const UV_CONSTRAINT: &'static str = "UV_CONSTRAINT";
|
||||
|
||||
/// Equivalent to the `--build-constraint` argument. Path to build constraints file.
|
||||
/// Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file
|
||||
/// as constraints for any source distribution builds. Uses space-separated list of files.
|
||||
pub const UV_BUILD_CONSTRAINT: &'static str = "UV_BUILD_CONSTRAINT";
|
||||
|
||||
/// Equivalent to the `--override` argument. Path to overrides file.
|
||||
/// Equivalent to the `--override` command-line argument. If set, uv will use this file
|
||||
/// as the overrides file. Uses space-separated list of files.
|
||||
pub const UV_OVERRIDE: &'static str = "UV_OVERRIDE";
|
||||
|
||||
/// Equivalent to the `--link-mode` argument. Specifies link mode for the installation.
|
||||
/// Equivalent to the `--link-mode` command-line argument. If set, uv will use this as
|
||||
/// a link mode.
|
||||
pub const UV_LINK_MODE: &'static str = "UV_LINK_MODE";
|
||||
|
||||
/// Equivalent to the `--no-build-isolation` argument. Skips build isolation.
|
||||
/// Equivalent to the `--no-build-isolation` command-line argument. If set, uv will
|
||||
/// skip isolation when building source distributions.
|
||||
pub const UV_NO_BUILD_ISOLATION: &'static str = "UV_NO_BUILD_ISOLATION";
|
||||
|
||||
/// Equivalent to the `--custom-compile-command` argument. Overrides the command in `requirements.txt`.
|
||||
/// Equivalent to the `--custom-compile-command` command-line argument.
|
||||
/// Used to override uv in the output header of the `requirements.txt` files generated by
|
||||
/// `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper
|
||||
/// script, to include the name of the wrapper script in the output file.
|
||||
pub const UV_CUSTOM_COMPILE_COMMAND: &'static str = "UV_CUSTOM_COMPILE_COMMAND";
|
||||
|
||||
/// Equivalent to the `--keyring-provider` argument. Specifies keyring provider.
|
||||
/// Equivalent to the `--keyring-provider` command-line argument. If set, uv
|
||||
/// will use this value as the keyring provider.
|
||||
pub const UV_KEYRING_PROVIDER: &'static str = "UV_KEYRING_PROVIDER";
|
||||
|
||||
/// Equivalent to the `--config-file` argument. Path to configuration file.
|
||||
/// Equivalent to the `--config-file` command-line argument. Expects a path to a
|
||||
/// local `uv.toml` file to use as the configuration file.
|
||||
pub const UV_CONFIG_FILE: &'static str = "UV_CONFIG_FILE";
|
||||
|
||||
/// Equivalent to the `--no-config` argument. Prevents reading configuration files.
|
||||
/// Equivalent to the `--no-config` command-line argument. If set, uv will not read
|
||||
/// any configuration files from the current directory, parent directories, or user configuration
|
||||
/// directories.
|
||||
pub const UV_NO_CONFIG: &'static str = "UV_NO_CONFIG";
|
||||
|
||||
/// Equivalent to the `--exclude-newer` argument. Excludes newer distributions after a date.
|
||||
/// Equivalent to the `--exclude-newer` command-line argument. If set, uv will
|
||||
/// exclude distributions published after the specified date.
|
||||
pub const UV_EXCLUDE_NEWER: &'static str = "UV_EXCLUDE_NEWER";
|
||||
|
||||
/// Equivalent to the `--python-preference` argument. Controls preference for Python versions.
|
||||
/// Equivalent to the `--python-preference` command-line argument. Whether uv
|
||||
/// should prefer system or managed Python versions.
|
||||
pub const UV_PYTHON_PREFERENCE: &'static str = "UV_PYTHON_PREFERENCE";
|
||||
|
||||
/// Equivalent to the `--no-python-downloads` argument. Disables Python downloads.
|
||||
/// Equivalent to the
|
||||
/// [`python-downloads`](../reference/settings.md#python-downloads) setting and, when disabled, the
|
||||
/// `--no-python-downloads` option. Whether uv should allow Python downloads.
|
||||
pub const UV_PYTHON_DOWNLOADS: &'static str = "UV_PYTHON_DOWNLOADS";
|
||||
|
||||
/// Equivalent to the `--compile-bytecode` argument. Compiles Python source to bytecode.
|
||||
/// Equivalent to the `--compile-bytecode` command-line argument. If set, uv
|
||||
/// will compile Python source files to bytecode after installation.
|
||||
pub const UV_COMPILE_BYTECODE: &'static str = "UV_COMPILE_BYTECODE";
|
||||
|
||||
/// Equivalent to the `--publish-url` argument. URL for publishing packages.
|
||||
/// Equivalent to the `--publish-url` command-line argument. The URL of the upload
|
||||
/// endpoint of the index to use with `uv publish`.
|
||||
pub const UV_PUBLISH_URL: &'static str = "UV_PUBLISH_URL";
|
||||
|
||||
/// Equivalent to the `--token` argument in `uv publish`. Token for publishing.
|
||||
/// Equivalent to the `--token` command-line argument in `uv publish`. If set, uv
|
||||
/// will use this token (with the username `__token__`) for publishing.
|
||||
pub const UV_PUBLISH_TOKEN: &'static str = "UV_PUBLISH_TOKEN";
|
||||
|
||||
/// Equivalent to the `--username` argument in `uv publish`. Username for publishing.
|
||||
/// Equivalent to the `--username` command-line argument in `uv publish`. If
|
||||
/// set, uv will use this username for publishing.
|
||||
pub const UV_PUBLISH_USERNAME: &'static str = "UV_PUBLISH_USERNAME";
|
||||
|
||||
/// Equivalent to the `--password` argument in `uv publish`. Password for publishing.
|
||||
/// Equivalent to the `--password` command-line argument in `uv publish`. If
|
||||
/// set, uv will use this password for publishing.
|
||||
pub const UV_PUBLISH_PASSWORD: &'static str = "UV_PUBLISH_PASSWORD";
|
||||
|
||||
/// Don't upload a file if it already exists on the index. The value is the URL of the index.
|
||||
pub const UV_PUBLISH_CHECK_URL: &'static str = "UV_PUBLISH_CHECK_URL";
|
||||
|
||||
/// Equivalent to the `--no-sync` argument. Skips syncing the environment.
|
||||
/// Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating
|
||||
/// the environment.
|
||||
pub const UV_NO_SYNC: &'static str = "UV_NO_SYNC";
|
||||
|
||||
/// Equivalent to the `--locked` argument. Assert that the `uv.lock` will remain unchanged.
|
||||
/// Equivalent to the `--locked` command-line argument. If set, uv will assert that the
|
||||
/// `uv.lock` remains unchanged.
|
||||
pub const UV_LOCKED: &'static str = "UV_LOCKED";
|
||||
|
||||
/// Equivalent to the `--frozen` argument. Run without updating the `uv.lock` file.
|
||||
/// Equivalent to the `--frozen` command-line argument. If set, uv will run without
|
||||
/// updating the `uv.lock` file.
|
||||
pub const UV_FROZEN: &'static str = "UV_FROZEN";
|
||||
|
||||
/// Equivalent to the `--preview` argument. Enables preview mode.
|
||||
|
|
@ -126,22 +173,27 @@ impl EnvVars {
|
|||
/// Equivalent to the `--allow-insecure-host` argument.
|
||||
pub const UV_INSECURE_HOST: &'static str = "UV_INSECURE_HOST";
|
||||
|
||||
/// Sets the maximum number of in-flight concurrent downloads.
|
||||
/// Sets the maximum number of in-flight concurrent downloads that uv will
|
||||
/// perform at any given time.
|
||||
pub const UV_CONCURRENT_DOWNLOADS: &'static str = "UV_CONCURRENT_DOWNLOADS";
|
||||
|
||||
/// Sets the maximum number of concurrent builds for source distributions.
|
||||
/// Sets the maximum number of source distributions that uv will build
|
||||
/// concurrently at any given time.
|
||||
pub const UV_CONCURRENT_BUILDS: &'static str = "UV_CONCURRENT_BUILDS";
|
||||
|
||||
/// Controls the number of threads used for concurrent installations.
|
||||
/// Controls the number of threads used when installing and unzipping
|
||||
/// packages.
|
||||
pub const UV_CONCURRENT_INSTALLS: &'static str = "UV_CONCURRENT_INSTALLS";
|
||||
|
||||
/// Specifies the directory where `uv` stores managed tools.
|
||||
/// Specifies the directory where uv stores managed tools.
|
||||
pub const UV_TOOL_DIR: &'static str = "UV_TOOL_DIR";
|
||||
|
||||
/// Specifies the "bin" directory for installing tool executables.
|
||||
pub const UV_TOOL_BIN_DIR: &'static str = "UV_TOOL_BIN_DIR";
|
||||
|
||||
/// Specifies the path to the project virtual environment.
|
||||
/// Specifies the path to the directory to use for a project virtual environment.
|
||||
/// See the [project documentation](../concepts/projects.md#configuring-the-project-environment-path)
|
||||
/// for more details.
|
||||
pub const UV_PROJECT_ENVIRONMENT: &'static str = "UV_PROJECT_ENVIRONMENT";
|
||||
|
||||
/// Specifies the directory to place links to installed, managed Python executables.
|
||||
|
|
@ -150,19 +202,32 @@ impl EnvVars {
|
|||
/// Specifies the directory for storing managed Python installations.
|
||||
pub const UV_PYTHON_INSTALL_DIR: &'static str = "UV_PYTHON_INSTALL_DIR";
|
||||
|
||||
/// Mirror URL for downloading managed Python installations.
|
||||
/// Managed Python installations are downloaded from
|
||||
/// [`python-build-standalone`](https://github.com/indygreg/python-build-standalone).
|
||||
/// This variable can be set to a mirror URL to use a different source for Python installations.
|
||||
/// The provided URL will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g.,
|
||||
/// `https://github.com/indygreg/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
|
||||
/// Distributions can be read from a local directory by using the `file://` URL scheme.
|
||||
pub const UV_PYTHON_INSTALL_MIRROR: &'static str = "UV_PYTHON_INSTALL_MIRROR";
|
||||
|
||||
/// Mirror URL for downloading managed PyPy installations.
|
||||
/// Managed PyPy installations are downloaded from
|
||||
/// [python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a
|
||||
/// different source for PyPy installations. The provided URL will replace
|
||||
/// `https://downloads.python.org/pypy` in, e.g.,
|
||||
/// `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
|
||||
/// Distributions can be read from a local directory by using the `file://` URL scheme.
|
||||
pub const UV_PYPY_INSTALL_MIRROR: &'static str = "UV_PYPY_INSTALL_MIRROR";
|
||||
|
||||
/// Used to override `PATH` to limit Python executable availability in the test suite.
|
||||
#[attr_hidden]
|
||||
pub const UV_TEST_PYTHON_PATH: &'static str = "UV_TEST_PYTHON_PATH";
|
||||
|
||||
/// Include resolver and installer output related to environment modifications.
|
||||
#[attr_hidden]
|
||||
pub const UV_SHOW_RESOLUTION: &'static str = "UV_SHOW_RESOLUTION";
|
||||
|
||||
/// Use to update the json schema files.
|
||||
#[attr_hidden]
|
||||
pub const UV_UPDATE_SCHEMA: &'static str = "UV_UPDATE_SCHEMA";
|
||||
|
||||
/// Use to disable line wrapping for diagnostics.
|
||||
|
|
@ -172,37 +237,47 @@ impl EnvVars {
|
|||
pub const UV_STACK_SIZE: &'static str = "UV_STACK_SIZE";
|
||||
|
||||
/// Generates the environment variable key for the HTTP Basic authentication username.
|
||||
#[attr_env_var_pattern("UV_INDEX_{name}_USERNAME")]
|
||||
pub fn index_username(name: &str) -> String {
|
||||
format!("UV_INDEX_{name}_USERNAME")
|
||||
}
|
||||
|
||||
/// Generates the environment variable key for the HTTP Basic authentication password.
|
||||
#[attr_env_var_pattern("UV_INDEX_{name}_PASSWORD")]
|
||||
pub fn index_password(name: &str) -> String {
|
||||
format!("UV_INDEX_{name}_PASSWORD")
|
||||
}
|
||||
|
||||
/// Used to set the uv commit hash at build time via `build.rs`.
|
||||
#[attr_hidden]
|
||||
pub const UV_COMMIT_HASH: &'static str = "UV_COMMIT_HASH";
|
||||
|
||||
/// Used to set the uv commit short hash at build time via `build.rs`.
|
||||
#[attr_hidden]
|
||||
pub const UV_COMMIT_SHORT_HASH: &'static str = "UV_COMMIT_SHORT_HASH";
|
||||
|
||||
/// Used to set the uv commit date at build time via `build.rs`.
|
||||
#[attr_hidden]
|
||||
pub const UV_COMMIT_DATE: &'static str = "UV_COMMIT_DATE";
|
||||
|
||||
/// Used to set the uv tag at build time via `build.rs`.
|
||||
#[attr_hidden]
|
||||
pub const UV_LAST_TAG: &'static str = "UV_LAST_TAG";
|
||||
|
||||
/// Used to set the uv tag distance from head at build time via `build.rs`.
|
||||
#[attr_hidden]
|
||||
pub const UV_LAST_TAG_DISTANCE: &'static str = "UV_LAST_TAG_DISTANCE";
|
||||
|
||||
/// Used to set the spawning/parent interpreter when using --system in the test suite.
|
||||
#[attr_hidden]
|
||||
pub const UV_INTERNAL__PARENT_INTERPRETER: &'static str = "UV_INTERNAL__PARENT_INTERPRETER";
|
||||
|
||||
/// Used to force showing the derivation tree during resolver error reporting.
|
||||
#[attr_hidden]
|
||||
pub const UV_INTERNAL__SHOW_DERIVATION_TREE: &'static str = "UV_INTERNAL__SHOW_DERIVATION_TREE";
|
||||
|
||||
/// Used to set a temporary directory for some tests.
|
||||
#[attr_hidden]
|
||||
pub const UV_INTERNAL__TEST_DIR: &'static str = "UV_INTERNAL__TEST_DIR";
|
||||
|
||||
/// Path to system-level configuration directory on Unix systems.
|
||||
|
|
@ -223,19 +298,11 @@ impl EnvVars {
|
|||
/// Path to directory where executables are installed.
|
||||
pub const XDG_BIN_HOME: &'static str = "XDG_BIN_HOME";
|
||||
|
||||
/// Timeout (in seconds) for HTTP requests.
|
||||
pub const UV_HTTP_TIMEOUT: &'static str = "UV_HTTP_TIMEOUT";
|
||||
|
||||
/// Timeout (in seconds) for HTTP requests.
|
||||
pub const UV_REQUEST_TIMEOUT: &'static str = "UV_REQUEST_TIMEOUT";
|
||||
|
||||
/// Timeout (in seconds) for HTTP requests.
|
||||
pub const HTTP_TIMEOUT: &'static str = "HTTP_TIMEOUT";
|
||||
|
||||
/// Custom certificate bundle file path for SSL connections.
|
||||
pub const SSL_CERT_FILE: &'static str = "SSL_CERT_FILE";
|
||||
|
||||
/// File for mTLS authentication (contains certificate and private key).
|
||||
/// If set, uv will use this file for mTLS authentication.
|
||||
/// This should be a single file containing both the certificate and the private key in PEM format.
|
||||
pub const SSL_CLIENT_CERT: &'static str = "SSL_CLIENT_CERT";
|
||||
|
||||
/// Proxy for HTTP requests.
|
||||
|
|
@ -247,16 +314,31 @@ impl EnvVars {
|
|||
/// General proxy for all network requests.
|
||||
pub const ALL_PROXY: &'static str = "ALL_PROXY";
|
||||
|
||||
/// Timeout (in seconds) for HTTP requests. (default: 30 s)
|
||||
pub const UV_HTTP_TIMEOUT: &'static str = "UV_HTTP_TIMEOUT";
|
||||
|
||||
/// Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
|
||||
pub const UV_REQUEST_TIMEOUT: &'static str = "UV_REQUEST_TIMEOUT";
|
||||
|
||||
/// Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
|
||||
pub const HTTP_TIMEOUT: &'static str = "HTTP_TIMEOUT";
|
||||
|
||||
/// The validation modes to use when run with `--compile`.
|
||||
///
|
||||
/// See [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode).
|
||||
pub const PYC_INVALIDATION_MODE: &'static str = "PYC_INVALIDATION_MODE";
|
||||
|
||||
/// Used to detect an activated virtual environment.
|
||||
pub const VIRTUAL_ENV: &'static str = "VIRTUAL_ENV";
|
||||
|
||||
/// Used to detect an activated Conda environment.
|
||||
pub const CONDA_PREFIX: &'static str = "CONDA_PREFIX";
|
||||
|
||||
/// Disables prepending virtual environment name to the terminal prompt.
|
||||
/// If set to `1` before a virtual environment is activated, then the
|
||||
/// virtual environment name will not be prepended to the terminal prompt.
|
||||
pub const VIRTUAL_ENV_DISABLE_PROMPT: &'static str = "VIRTUAL_ENV_DISABLE_PROMPT";
|
||||
|
||||
/// Used to detect Windows Command Prompt usage.
|
||||
/// Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
|
||||
pub const PROMPT: &'static str = "PROMPT";
|
||||
|
||||
/// Used to detect `NuShell` usage.
|
||||
|
|
@ -277,16 +359,23 @@ impl EnvVars {
|
|||
/// Used to detect Ksh shell usage.
|
||||
pub const KSH_VERSION: &'static str = "KSH_VERSION";
|
||||
|
||||
/// Sets macOS deployment target when using `--python-platform macos`.
|
||||
/// Used with `--python-platform macos` and related variants to set the
|
||||
/// deployment target (i.e., the minimum supported macOS version).
|
||||
///
|
||||
/// Defaults to `12.0`, the least-recent non-EOL macOS version at time of writing.
|
||||
pub const MACOSX_DEPLOYMENT_TARGET: &'static str = "MACOSX_DEPLOYMENT_TARGET";
|
||||
|
||||
/// Disables colored output (takes precedence over `FORCE_COLOR`).
|
||||
///
|
||||
/// See [no-color.org](https://no-color.org).
|
||||
pub const NO_COLOR: &'static str = "NO_COLOR";
|
||||
|
||||
/// Disables all progress output. For example, spinners and progress bars.
|
||||
pub const UV_NO_PROGRESS: &'static str = "UV_NO_PROGRESS";
|
||||
|
||||
/// Forces colored output regardless of terminal support.
|
||||
///
|
||||
/// See [force-color.org](https://force-color.org).
|
||||
pub const FORCE_COLOR: &'static str = "FORCE_COLOR";
|
||||
|
||||
/// Use to control color via `anstyle`.
|
||||
|
|
@ -372,34 +461,47 @@ impl EnvVars {
|
|||
pub const TRACING_DURATIONS_FILE: &'static str = "TRACING_DURATIONS_FILE";
|
||||
|
||||
/// Used to set `RUST_HOST_TARGET` at build time via `build.rs`.
|
||||
#[attr_hidden]
|
||||
pub const TARGET: &'static str = "TARGET";
|
||||
|
||||
/// Custom log level for verbose output, compatible with `tracing_subscriber`.
|
||||
/// If set, uv will use this value as the log level for its `--verbose` output. Accepts
|
||||
/// any filter compatible with the `tracing_subscriber` crate.
|
||||
/// For example, `RUST_LOG=trace` will enable trace-level logging.
|
||||
/// See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
|
||||
/// for more.
|
||||
pub const RUST_LOG: &'static str = "RUST_LOG";
|
||||
|
||||
/// The directory containing the `Cargo.toml` manifest for a package.
|
||||
#[attr_hidden]
|
||||
pub const CARGO_MANIFEST_DIR: &'static str = "CARGO_MANIFEST_DIR";
|
||||
|
||||
/// Specifies the directory where Cargo stores build artifacts (target directory).
|
||||
#[attr_hidden]
|
||||
pub const CARGO_TARGET_DIR: &'static str = "CARGO_TARGET_DIR";
|
||||
|
||||
/// Used in tests for environment substitution testing in `requirements.in`.
|
||||
#[attr_hidden]
|
||||
pub const URL: &'static str = "URL";
|
||||
|
||||
/// Used in tests for environment substitution testing in `requirements.in`.
|
||||
#[attr_hidden]
|
||||
pub const FILE_PATH: &'static str = "FILE_PATH";
|
||||
|
||||
/// Used in tests for environment substitution testing in `requirements.in`.
|
||||
#[attr_hidden]
|
||||
pub const HATCH_PATH: &'static str = "HATCH_PATH";
|
||||
|
||||
/// Used in tests for environment substitution testing in `requirements.in`.
|
||||
#[attr_hidden]
|
||||
pub const BLACK_PATH: &'static str = "BLACK_PATH";
|
||||
|
||||
/// Used in testing Hatch's root.uri feature
|
||||
///
|
||||
/// See: <https://hatch.pypa.io/dev/config/dependency/#local>.
|
||||
#[attr_hidden]
|
||||
pub const ROOT_PATH: &'static str = "ROOT_PATH";
|
||||
|
||||
/// Used to set test credentials for keyring tests.
|
||||
#[attr_hidden]
|
||||
pub const KEYRING_TEST_CREDENTIALS: &'static str = "KEYRING_TEST_CREDENTIALS";
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
# Environment variables
|
||||
|
||||
uv accepts the following command-line arguments as environment variables:
|
||||
uv respects the following environment variables:
|
||||
|
||||
- `UV_INDEX`: Equivalent to the `--index` command-line argument. If set, uv will use this
|
||||
space-separated list of URLs as additional indexes when searching for packages.
|
||||
- `UV_DEFAULT_INDEX`: Equivalent to the `--default-index` command-line argument. If set, uv will use
|
||||
this URL as the default index when searching for packages.
|
||||
- `UV_INDEX`: Equivalent to the `--index` command-line argument. If set, uv will use this
|
||||
space-separated list of URLs as additional indexes when searching for packages.
|
||||
- `UV_INDEX_URL`: Equivalent to the `--index-url` command-line argument. If set, uv will use this
|
||||
URL as the default index when searching for packages. (Deprecated: use `UV_DEFAULT_INDEX`
|
||||
instead.)
|
||||
URL as the default index when searching for packages.
|
||||
(Deprecated: use `UV_DEFAULT_INDEX` instead.)
|
||||
- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv will
|
||||
use this space-separated list of URLs as additional indexes when searching for packages.
|
||||
(Deprecated: use `UV_INDEX` instead.)
|
||||
|
|
@ -23,16 +23,17 @@ uv accepts the following command-line arguments as environment variables:
|
|||
- `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to
|
||||
`allow`, uv will allow pre-release versions for all dependencies.
|
||||
- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv will
|
||||
use the first Python interpreter found in the system `PATH`. WARNING: `UV_SYSTEM_PYTHON=true` is
|
||||
intended for use in continuous integration (CI) or containerized environments and should be used
|
||||
with caution, as modifying the system Python can lead to unexpected behavior.
|
||||
use the first Python interpreter found in the system `PATH`.
|
||||
WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI)
|
||||
or containerized environments and should be used with caution, as modifying the system
|
||||
Python can lead to unexpected behavior.
|
||||
- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will use
|
||||
this Python interpreter for all operations.
|
||||
- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If
|
||||
set to `true`, uv will allow the installation of packages that conflict with system-installed
|
||||
packages. WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
|
||||
(CI) or containerized environments and should be used with caution, as modifying the system Python
|
||||
can lead to unexpected behavior.
|
||||
- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If set to `true`,
|
||||
uv will allow the installation of packages that conflict with system-installed packages.
|
||||
WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
|
||||
(CI) or containerized environments and should be used with caution, as modifying the system
|
||||
Python can lead to unexpected behavior.
|
||||
- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will
|
||||
use the system's trust store instead of the bundled `webpki-roots` crate.
|
||||
- `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` command-line argument. For example, if
|
||||
|
|
@ -42,15 +43,14 @@ uv accepts the following command-line arguments as environment variables:
|
|||
uv will require that all dependencies have a hash specified in the requirements file.
|
||||
- `UV_CONSTRAINT`: Equivalent to the `--constraint` command-line argument. If set, uv will use this
|
||||
file as the constraints file. Uses space-separated list of files.
|
||||
- `UV_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv
|
||||
will use this file as constraints for any source distribution builds. Uses space-separated list of
|
||||
files.
|
||||
- `UV_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file
|
||||
as constraints for any source distribution builds. Uses space-separated list of files.
|
||||
- `UV_OVERRIDE`: Equivalent to the `--override` command-line argument. If set, uv will use this file
|
||||
as the overrides file. Uses space-separated list of files.
|
||||
- `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as
|
||||
a link mode.
|
||||
- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set,
|
||||
uv will skip isolation when building source distributions.
|
||||
- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, uv will
|
||||
skip isolation when building source distributions.
|
||||
- `UV_CUSTOM_COMPILE_COMMAND`: Equivalent to the `--custom-compile-command` command-line argument.
|
||||
Used to override uv in the output header of the `requirements.txt` files generated by
|
||||
`uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper
|
||||
|
|
@ -79,78 +79,115 @@ uv accepts the following command-line arguments as environment variables:
|
|||
set, uv will use this username for publishing.
|
||||
- `UV_PUBLISH_PASSWORD`: Equivalent to the `--password` command-line argument in `uv publish`. If
|
||||
set, uv will use this password for publishing.
|
||||
- `UV_PUBLISH_CHECK_URL`: Don't upload a file if it already exists on the index. The value is the URL of the index.
|
||||
- `UV_NO_SYNC`: Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating
|
||||
the environment.
|
||||
- `UV_LOCKED`: Equivalent to the `--locked` command-line argument. If set, uv will assert that the
|
||||
`uv.lock` remains unchanged.
|
||||
- `UV_FROZEN`: Equivalent to the `--frozen` command-line argument. If set, uv will run without
|
||||
updating the `uv.lock` file.
|
||||
|
||||
In each case, the corresponding command-line argument takes precedence over an environment variable.
|
||||
|
||||
In addition, uv respects the following environment variables:
|
||||
|
||||
- `UV_PREVIEW`: Equivalent to the `--preview` argument. Enables preview mode.
|
||||
- `UV_GITHUB_TOKEN`: Equivalent to the `--token` argument for self update. A GitHub token for authentication.
|
||||
- `UV_VERIFY_HASHES`: Equivalent to the `--verify-hashes` argument. Verifies included hashes.
|
||||
- `UV_INSECURE_HOST`: Equivalent to the `--allow-insecure-host` argument.
|
||||
- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will
|
||||
perform at any given time.
|
||||
- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build
|
||||
concurrently at any given time.
|
||||
- `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping
|
||||
- `UV_CONCURRENT_INSTALLS`: Controls the number of threads used when installing and unzipping
|
||||
packages.
|
||||
- `UV_TOOL_DIR`: Used to specify the directory where uv will store managed tools.
|
||||
- `UV_TOOL_BIN_DIR`: Used to specify the "bin" directory where uv will install tool executables.
|
||||
- `UV_PROJECT_ENVIRONMENT`: Use to specify the path to the directory to use for a project virtual
|
||||
environment. See the
|
||||
[project documentation](../concepts/projects.md#configuring-the-project-environment-path) for more
|
||||
details.
|
||||
- `UV_PYTHON_INSTALL_DIR`: Used to specify the directory where uv will store managed Python
|
||||
installations.
|
||||
- `UV_TOOL_DIR`: Specifies the directory where uv stores managed tools.
|
||||
- `UV_TOOL_BIN_DIR`: Specifies the "bin" directory for installing tool executables.
|
||||
- `UV_PROJECT_ENVIRONMENT`: Specifies the path to the directory to use for a project virtual environment.
|
||||
See the [project documentation](../concepts/projects.md#configuring-the-project-environment-path)
|
||||
for more details.
|
||||
- `UV_PYTHON_BIN_DIR`: Specifies the directory to place links to installed, managed Python executables.
|
||||
- `UV_PYTHON_INSTALL_DIR`: Specifies the directory for storing managed Python installations.
|
||||
- `UV_PYTHON_INSTALL_MIRROR`: Managed Python installations are downloaded from
|
||||
[`python-build-standalone`](https://github.com/indygreg/python-build-standalone). This variable
|
||||
can be set to a mirror URL to use a different source for Python installations. The provided URL
|
||||
will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g.,
|
||||
[`python-build-standalone`](https://github.com/indygreg/python-build-standalone).
|
||||
This variable can be set to a mirror URL to use a different source for Python installations.
|
||||
The provided URL will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g.,
|
||||
`https://github.com/indygreg/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
|
||||
Distributions can be read from a local directory by using the `file://` URL scheme.
|
||||
- `UV_PYPY_INSTALL_MIRROR`: Managed PyPy installations are downloaded from
|
||||
[python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a
|
||||
different source for PyPy installations. The provided URL will replace
|
||||
`https://downloads.python.org/pypy` in, e.g.,
|
||||
`https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`. Distributions can be read from a
|
||||
local directory by using the `file://` URL scheme.
|
||||
- `XDG_CONFIG_HOME`: Used to specify the path to uv user-level configuration directory on Unix
|
||||
systems.
|
||||
- `XDG_CACHE_HOME`: Used to specify the directory where uv stores cache files on Unix systems.
|
||||
- `XDG_DATA_HOME`: Used to specify the directory where uv stores managed Python installations and
|
||||
managed tools on Unix systems.
|
||||
- `XDG_BIN_HOME`: Used to specify the directory where executables are installed into.
|
||||
- `SSL_CERT_FILE`: If set, uv will use this file as the certificate bundle instead of the system's
|
||||
trust store.
|
||||
- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication. This should be a single
|
||||
file containing both the certificate and the private key in PEM format.
|
||||
- `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts
|
||||
any filter compatible with the `tracing_subscriber` crate. For example, `RUST_LOG=trace` will
|
||||
enable trace-level logging. See the
|
||||
[tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
|
||||
for more.
|
||||
- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests.
|
||||
- `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout
|
||||
for HTTP reads (default: 30 s).
|
||||
- `NETRC`: If set, uv will read authentication information from this file instead of `~/.netrc`.
|
||||
- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. See:
|
||||
[`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode).
|
||||
`https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
|
||||
Distributions can be read from a local directory by using the `file://` URL scheme.
|
||||
- `UV_NO_WRAP`: Use to disable line wrapping for diagnostics.
|
||||
- `UV_STACK_SIZE`: Use to control the stack size used by uv. Typically more relevant for Windows in debug mode.
|
||||
- `UV_INDEX_{name}_USERNAME`: Generates the environment variable key for the HTTP Basic authentication username.
|
||||
- `UV_INDEX_{name}_PASSWORD`: Generates the environment variable key for the HTTP Basic authentication password.
|
||||
- `XDG_CONFIG_DIRS`: Path to system-level configuration directory on Unix systems.
|
||||
- `SYSTEMDRIVE`: Path to system-level configuration directory on Windows systems.
|
||||
- `XDG_CONFIG_HOME`: Path to user-level configuration directory on Unix systems.
|
||||
- `XDG_CACHE_HOME`: Path to cache directory on Unix systems.
|
||||
- `XDG_DATA_HOME`: Path to directory for storing managed Python installations and tools.
|
||||
- `XDG_BIN_HOME`: Path to directory where executables are installed.
|
||||
- `SSL_CERT_FILE`: Custom certificate bundle file path for SSL connections.
|
||||
- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication.
|
||||
This should be a single file containing both the certificate and the private key in PEM format.
|
||||
- `HTTP_PROXY`: Proxy for HTTP requests.
|
||||
- `HTTPS_PROXY`: Proxy for HTTPS requests.
|
||||
- `ALL_PROXY`: General proxy for all network requests.
|
||||
- `UV_HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. (default: 30 s)
|
||||
- `UV_REQUEST_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
|
||||
- `HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
|
||||
- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`.
|
||||
See [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode).
|
||||
- `VIRTUAL_ENV`: Used to detect an activated virtual environment.
|
||||
- `CONDA_PREFIX`: Used to detect an activated Conda environment.
|
||||
- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
|
||||
- `VIRTUAL_ENV_DISABLE_PROMPT`: If set to `1` before a virtual environment is activated, then the
|
||||
virtual environment name will not be prepended to the terminal prompt.
|
||||
- `NU_VERSION`: Used to detect the use of NuShell.
|
||||
- `FISH_VERSION`: Used to detect the use of the Fish shell.
|
||||
- `BASH_VERSION`: Used to detect the use of the Bash shell.
|
||||
- `ZSH_VERSION`: Used to detect the use of the Zsh shell.
|
||||
- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
|
||||
- `NU_VERSION`: Used to detect `NuShell` usage.
|
||||
- `FISH_VERSION`: Used to detect Fish shell usage.
|
||||
- `BASH_VERSION`: Used to detect Bash shell usage.
|
||||
- `ZSH_VERSION`: Used to detect Zsh shell usage.
|
||||
- `ZDOTDIR`: Used to determine which `.zshenv` to use when Zsh is being used.
|
||||
- `KSH_VERSION`: Used to detect Ksh shell usage.
|
||||
- `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the
|
||||
deployment target (i.e., the minimum supported macOS version). Defaults to `12.0`, the
|
||||
least-recent non-EOL macOS version at time of writing.
|
||||
- `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See
|
||||
[no-color.org](https://no-color.org).
|
||||
- `UV_NO_PROGRESS`: Disable progress indicators like spinners and progress bars.
|
||||
- `FORCE_COLOR`: Enforce colors regardless of TTY support. See
|
||||
[force-color.org](https://force-color.org).
|
||||
deployment target (i.e., the minimum supported macOS version).
|
||||
Defaults to `12.0`, the least-recent non-EOL macOS version at time of writing.
|
||||
- `NO_COLOR`: Disables colored output (takes precedence over `FORCE_COLOR`).
|
||||
See [no-color.org](https://no-color.org).
|
||||
- `UV_NO_PROGRESS`: Disables all progress output. For example, spinners and progress bars.
|
||||
- `FORCE_COLOR`: Forces colored output regardless of terminal support.
|
||||
See [force-color.org](https://force-color.org).
|
||||
- `CLICOLOR_FORCE`: Use to control color via `anstyle`.
|
||||
- `PATH`: The standard `PATH` env var.
|
||||
- `HOME`: The standard `HOME` env var.
|
||||
- `SHELL`: The standard `SHELL` posix env var.
|
||||
- `PWD`: The standard `PWD` posix env var.
|
||||
- `LOCALAPPDATA`: Used to look for Microsoft Store Pythons installations.
|
||||
- `GIT_DIR`: Path to the `.git` directory. Ignored by `uv` when performing fetch.
|
||||
- `GIT_WORK_TREE`: Path to the git working tree. Ignored by `uv` when performing fetch.
|
||||
- `GIT_INDEX_FILE`: Path to the index file for staged changes. Ignored by `uv` when performing fetch.
|
||||
- `GIT_OBJECT_DIRECTORY`: Path to where git object files are located. Ignored by `uv` when performing fetch.
|
||||
- `GIT_ALTERNATE_OBJECT_DIRECTORIES`: Alternate locations for git objects. Ignored by `uv` when performing fetch.
|
||||
- `GIT_CEILING_DIRECTORIES`: Used in tests for better git isolation.
|
||||
For example, we run some tests in ~/.local/share/uv/tests.
|
||||
And if the user's `$HOME` directory is a git repository,
|
||||
this will change the behavior of some tests. Setting
|
||||
`GIT_CEILING_DIRECTORIES=/home/andrew/.local/share/uv/tests` will
|
||||
prevent git from crawling up the directory tree past that point to find
|
||||
parent git repositories.
|
||||
- `GITHUB_ACTIONS`: Used for trusted publishing via `uv publish`.
|
||||
- `ACTIONS_ID_TOKEN_REQUEST_URL`: Used for trusted publishing via `uv publish`. Contains the oidc token url.
|
||||
- `ACTIONS_ID_TOKEN_REQUEST_TOKEN`: Used for trusted publishing via `uv publish`. Contains the oidc request token.
|
||||
- `PYTHONIOENCODING`: Sets the encoding for standard I/O streams (e.g., PYTHONIOENCODING=utf-8).
|
||||
- `PYTHONUNBUFFERED`: Forces unbuffered I/O streams, equivalent to `-u` in Python.
|
||||
- `PYTHONUTF8`: Enables UTF-8 mode for Python, equivalent to `-X utf8`.
|
||||
- `PYTHONPATH`: Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules).
|
||||
- `CI`: Typically set by CI runners, used to detect a CI runner.
|
||||
- `NETRC`: Use to set the .netrc file location.
|
||||
- `PAGER`: The standard `PAGER` posix env var. Used by `uv` to configure the appropriate pager.
|
||||
- `JPY_SESSION_NAME`: Used to detect when running inside a Jupyter notebook.
|
||||
- `TRACING_DURATIONS_TEST_ROOT`: Use to create the tracing root directory via the `tracing-durations-export` feature.
|
||||
- `TRACING_DURATIONS_FILE`: Use to create the tracing durations file via the `tracing-durations-export` feature.
|
||||
- `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts
|
||||
any filter compatible with the `tracing_subscriber` crate.
|
||||
For example, `RUST_LOG=trace` will enable trace-level logging.
|
||||
See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
|
||||
for more.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue