# 🐍 Robust Python Development Environment on Garuda Linux (and macOS) This guide sets up a **robust and portable Python development environment**. > 🎯 Goals: > > - Isolated Python environments per project > - Fast dependency and environment management > - Clean shell integration (Fish) > - Editor integration with **WindSurf** > - Cross-platform usability via shell scripts ------ ## 🚀 Modern Python Stack with `uv` [`uv`](https://docs.astral.sh/uv/) by Astral is a modern, ultra-fast Python project and package manager written in Rust. It unifies and replaces tools like: - `pyenv` (Python version manager) - `virtualenv` / `venv` - `pip`, `pip-tools`, `pipx` - `poetry`, `hatch`, `twine` ------ ## ⚡ Why Use `uv` Over Traditional Tools? | Task | Old Tools | `uv` Replacement | | -------------------------- | ------------------------- | -------------------------- | | Install Python versions | `pyenv` | ✅ `uv python install` | | Create/manage environments | `virtualenv`, `hatch` | ✅ Built-in | | Dependency management | `pip`, `pip-tools` | ✅ Built-in | | Project scaffolding | `hatch new`, `poetry new` | ✅ `uv init` | | Build & publish packages | `hatch`, `twine` | ✅ `uv build`, `uv publish` | ------ ## 🧱 Setup Instructions ### 1. Install `uv` ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` Add `~/.cargo/bin` to your PATH if not already: ```fish set -Ux PATH $HOME/.cargo/bin $PATH ``` ------ ### 2. Create a New Project ```bash uv init myproject cd myproject ``` This scaffolds a `pyproject.toml`, `.gitignore`, and `main.py`. ------ ### 3. Install and Pin Python Version ```bash uv python install 3.12 uv python pin 3.12 ``` This installs Python and pins your project to it. ------ ### 4. Add Dependencies ```bash uv add requests rich typer ``` ------ ### 5. Run Code in the Environment ```bash uv run python main.py ``` Or launch an interactive shell: ```bash uv venv shell ``` ------ ### 6. Optional: Use `direnv` for Auto-Activation Install: ```bash sudo pacman -S direnv ``` Add to your `~/.config/fish/config.fish`: ```fish eval (direnv hook fish) ``` Then in your project: ```bash echo 'layout python' > .envrc direnv allow ``` ------ ### 7. Recommended Tools | Tool | Purpose | | --------- | ---------------------------------- | | `uv` | Python version, env, deps, publish | | `direnv` | Auto-load environments on `cd` | | `ipython` | Better REPL | | `black` | Code formatter | | `ruff` | Linter | | `zellij` | Terminal multiplexer | ------ ### 8. Editor: WindSurf Configuration WindSurf should: - Detect project interpreter from `.venv` - Use `ruff`, `black`, `pyright` - Support LSP for Python Install extras: ```bash uv add --dev black ruff ipython ``` ------ ## 🧪 Sample Project Workflow ```bash uv init py-test cd py-test uv python install 3.11 uv python pin 3.11 uv add requests uv run python main.py ``` ------ ## ✅ Summary | Component | Tool | | ------------------- | --------------- | | Python version mgmt | `uv` | | Virtual env mgmt | `uv` | | Dependency install | `uv` | | Terminal | `zellij` | | Editor | WindSurf | | Lint & Format | `ruff`, `black` | | Auto-activation | `direnv` | ------ ## 📂 Recommended Folder Structure ``` ~/Documents/projects/ ├── myproject │ ├── pyproject.toml │ ├── .venv/ (optional) │ ├── src/ │ └── README.md ``` ------ With `uv`, you no longer need to juggle between multiple tools like `pyenv`, `hatch`, and `pip`. You now have a **faster, unified, and cross-platform** experience. 🐍🚀