Standardize uv setup using environment variables for Python paths, caches, proxies, and custom indexes, as uv.toml is deprecated, ensuring consistent, transparent, and customizable configurations.
Foreword: If you're a Python developer, there's a good chance you've spent the past few years bouncing between pip, conda, poetry, and pipenv.Each tool offers specific strengths, yet each comes with frustrating trade-offs: sluggish performance, inconsistent lock files, or a disjointed approach to managing Python versions versus package dependencies. Then came uv. Developed by Astral—the team behind the Ruff linter—this Rust-based tool has a bold ambition: to serve as the "unified Swiss Army knife" of the Python ecosystem. It aims to replace pip, pip-tools, pipx, poetry, pyenv, and virtualenv with a single binary that operates an order of magnitude faster than its predecessors. In complex engineering environments, developers frequently encounter hurdles such as restrictive network proxies, limited disk space, and cross-platform environment inconsistencies. While uv provides a uv.toml configuration file, its design exhibits a degree of "asymmetry"—certain core paths, such as the Python installation directory, are exclusively configurable via environment variables. To achieve absolute consistency and maximum flexibility, this guide recommends bypassing uv.toml entirely in favor of managing uv exclusively through system-level environment variables.
Having previously relied on rye for project scaffolding and management, I transitioned to uv following the official announcement in February 2025 that rye would be deprecated. In production-grade development, only a few configurations truly matter: where the Python interpreter resides and where dependency caches are stored. Furthermore, network proxy configuration is a prerequisite for most development workflows, and machine learning projects often require custom index URLs for packages like PyTorch. By focusing on these four pillars, you can effectively standardize your uv configuration for nearly any use case.
The current design of uv presents a critical inconsistency in how configurations are handled:
This fragmentation means that relying solely on uv.toml leaves your environment incompletely configured. Standardizing on environment variables is currently the most professional and unambiguous approach for deep customization.
You can easily relocate uv’s data-heavy directories—specifically Python installations and the cache—away from your system drive (e.g., the C: drive) by using environment variables.
When you execute uv python install, uv downloads pre-compiled Python distributions from the python-build-standalone project.
uv’s high-speed dependency resolution relies entirely on its local cache.
Currently, uv relies heavily on environment variables for network management. Since uv does not provide an internal proxy toggle, it inherits standard proxy variables directly from the shell. In my view, given the complexity of real-world network environments—ranging from restricted corporate intranets and academic research networks to home proxy setups—it may eventually be necessary for uv to treat proxy settings as first-class configuration options rather than relying solely on shell-level inheritance. For now, my standard practice is to explicitly set proxy configurations in the current shell session before executing commands like uv add or uv sync.
If you are working within a corporate intranet or require a specific network configuration to fetch packages, you can define the following environment variables:
While global uv.toml configurations are deprecated, you must still manage project-specific package indexes—such as the PyTorch CUDA index—within your pyproject.toml using the [[tool.uv.index]] table. This approach treats index management as a core component of your project's dependency logic rather than a global tool preference.
Once you have configured your pyproject.toml, install the dependencies using the following commands:
Note: torch, torchvision, and torchaudio versions must be strictly aligned. Mismatched versions frequently lead to runtime errors. We strongly recommend pinning the minimum version requirements for all three packages in your pyproject.toml.
Standardizing environment variables brings transparency to your maintenance workflows, making operations straightforward and predictable.
uv has redefined developer productivity by delivering lightning-fast dependency resolution and a unified toolchain, making it an indispensable part of the modern Python stack. However, the sheer breadth of configuration options can be overwhelming for newcomers, often leaving them unsure of where to begin.
The core takeaway from this guide is simple: embrace environment variables and move away from uv.toml. This approach not only covers every configuration scenario—including critical settings like custom Python installation paths and proxy configurations that uv.toml cannot handle—but also ensures that your toolchain configuration remains consistent with your system-level environment, making it easier to audit and maintain.