Astral

Overview uv represents a paradigm shift in Python tooling. Developed by Astral in Rust, it acts as a high-performance replacement for `pip`, `poetry`, `pyenv`, and `virtualenv`. The primary advantage is speed; uv resolves and installs packages significantly faster than legacy tools while providing a unified interface for managing Python versions and virtual environments. Prerequisites To follow this guide, you should have a basic understanding of the Python ecosystem, including how to use the terminal and the purpose of a `pyproject.toml` file. While no specific version of Python is required to start—since uv can install Python for you—having a shell environment like Zsh or Bash is necessary. Key Libraries & Tools * **uv**: An extremely fast Python package and project manager. * **Ruff**: An extremely fast Python linter and formatter, also by Astral. * **Homebrew**: A macOS package manager used for easy installation. * **Cargo**: The Rust package manager, used if building uv from source. Code Walkthrough Installation On macOS, install via Homebrew: ```bash brew install uv ``` Alternatively, use a standalone script for any OS: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` Project Initialization Create a new project structure with a standard `pyproject.toml` and a managed virtual environment: ```bash uv init my-project cd my-project ``` This command generates a boilerplate Git setup, a `.python-version` file, and a basic `hello.py` script. Managing Dependencies Add and remove packages seamlessly. uv automatically updates your requirements and syncs the environment: ```bash uv add pandas fast-api uv remove sql-alchemy ``` Executing Code Run scripts directly within the context of your managed environment without manually activating it: ```bash uv run hello.py ``` Syntax Notes uv uses a command structure reminiscent of Cargo or `npm`. The `uvx` command (shorthand for `uv tool run`) allows for one-off execution of CLI tools like Ruff without permanently adding them to your project dependencies. Practical Examples In monorepo environments, uv supports **Workspaces**. This allows multiple projects to share a single lockfile and virtual environment, reducing disk usage and ensuring version consistency across different microservices or internal libraries. Tips & Gotchas * **Shell Completion**: Enable tab-completion for faster terminal navigation by running `uv generate-shell-completion zsh` and adding it to your config. * **Build Systems**: Currently, uv relies on backends like `hatchling` for building packages. It does not yet include a built-in Rust-based build backend, though this is actively being developed. * **Python Versions**: Use `uv python install 3.13` to manage runtimes without needing pyenv.