diff --git a/technology/applications/development/uv.md b/technology/applications/development/uv.md new file mode 100644 index 0000000..d197432 --- /dev/null +++ b/technology/applications/development/uv.md @@ -0,0 +1,238 @@ +--- +obj: application +repo: https://github.com/astral-sh/uv +website: https://docs.astral.sh/uv +rev: 2025-06-05 +--- + +# ๐Ÿš€ `uv` โ€“ Python Package and Project Manager +`uv` is a high-performance Python package manager and project toolchain, written in Rust. It consolidates functionalities from multiple tools into a single, fast, and efficient interface, aiming to replace `pip`, `pipx`, `poetry`, `pyenv`, `virtualenv`, `pip-tools`, `twine`, and more. + +## ๐Ÿ”ง Key Features + +* **Unified Tooling:** Combines functionalities of multiple tools into one. +* **Blazing Fast:** 10โ€“100x faster than `pip`. +* **Cross-Platform:** Supports macOS, Linux, and Windows. +* **Minimal Dependencies:** Single binary with no external dependencies. +* **Comprehensive Project Management:** Handles `pyproject.toml`, lockfiles, and more. +* **Python Version Management:** Install and manage multiple Python versions. +* **Tool Installation:** Install and run Python-based tools like `ruff`, `black`, etc. +* **Script Execution:** Run standalone Python scripts with inline dependencies. + +## โš™๏ธ Usage + +### Python Version Management + +* **Install Python Versions:** + + ```bash + uv python install 3.10.7 + ``` + +* **List Installed Versions:** + + ```bash + uv python list + ``` + +* **Pin Python Version for Project:** + + ```bash + uv python pin 3.10.7 + ``` + +* **Uninstall Python Version:** + + ```bash + uv python uninstall 3.10.7 + ``` + +### Virtual Environments + +* **Create a Virtual Environment:** + + ```bash + uv venv + ``` + +* **Create with Specific Python Version:** + + ```bash + uv venv --python 3.10 + ``` + +* **Activate the Environment:** + + ```bash + source .venv/bin/activate # macOS/Linux + .venv\Scripts\activate # Windows + ``` + +* **Install Dependencies:** + + ```bash + uv pip install -r requirements.txt + ``` + +* **Freeze Installed Packages:** + + ```bash + uv pip freeze > requirements.txt + ``` + +### Project Management + +* **Initialize a New Project:** + + ```bash + uv init my-project + ``` + +* **Add a Dependency:** + + ```bash + uv add requests + ``` + +* **Remove a Dependency:** + + ```bash + uv remove requests + ``` + +* **Sync Dependencies:** + + ```bash + uv sync + ``` + +* **Generate Lockfile:** + + ```bash + uv lock + ``` + +* **Run Project Scripts:** + + ```bash + uv run script.py + ``` + +* **Build Project:** + + ```bash + uv build + ``` + +* **Publish Project:** + + ```bash + uv publish + ``` + +### Tool Management + +* **Install a Tool:** + + ```bash + uv tool install black + ``` + +* **Uninstall a Tool:** + + ```bash + uv tool uninstall black + ``` + +* **Run a Tool:** + + ```bash + uv tool run black . + ``` + +* **List Installed Tools:** + + ```bash + uv tool list + ``` + + +### Running Python Scripts with Inline Dependencies +#### **Add Inline Metadata to Your Script** +To begin, you'll need to add metadata to your Python script to specify the required dependencies and Python version. This can be done using the `uv add --script` command: + +```bash +uv add --script your_script.py 'requests' 'numpy' +``` + +This command will modify your script to include a special comment block at the top, indicating the dependencies: + +```python +# /// script +# requires-python = ">=3.12" +# dependencies = [ +# "requests", +# "numpy", +# ] +# /// +``` + +#### **Make the Script Executable** +To run your script directly from the command line, add a shebang line at the very top of your script: + +```python +#!/usr/bin/env -S uv run --script +``` + +Ensure the script is executable: + +```bash +chmod +x your_script.py +``` + +#### **Run the Script** +Now, you can execute your script directly: +```bash +./your_script.py +``` + +The first time you run it, `uv` will create an isolated virtual environment, install the specified dependencies, and execute the script. On subsequent runs, the environment is cached, leading to near-instant execution times . + +## ๐Ÿ“ฆ Compatibility with Existing Tools +`uv` is designed to be compatible with existing Python tools and workflows: + +* **`pyproject.toml` Support:** Fully supports PEP 621-compliant `pyproject.toml` files. +* **`requirements.txt` Compatibility:** Works seamlessly with `requirements.txt` files. +* **`pip` Interface:** Provides a familiar `pip`-like interface for package management. +* **`pipx` Replacement:** Can install and run Python-based tools globally, replacing `pipx`. +* **`pyenv` Alternative:** Manages multiple Python versions without the need for `pyenv`. + +## ๐Ÿงช Example +Here's a typical workflow using `uv`: + +```bash +# Initialize a new project +uv init my-project + +# Navigate into the project directory +cd my-project + +# Create a virtual environment +uv venv + +# Activate the environment +source .venv/bin/activate # macOS/Linux +.venv\Scripts\activate # Windows + +# Add dependencies +uv add requests + +# Generate lockfile +uv lock + +# Install dependencies +uv sync + +# Run the project script +uv run script.py +```