add uv

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
+```