Python Dev Setup

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

curl -LsSf https://astral.sh/uv/install.sh | sh

Add ~/.cargo/bin to your PATH if not already:

set -Ux PATH $HOME/.cargo/bin $PATH

2. Create a New Project

uv init myproject
cd myproject

This scaffolds a pyproject.toml, .gitignore, and main.py.

3. Install and Pin Python Version

uv python install 3.12
uv python pin 3.12

This installs Python and pins your project to it.

4. Add Dependencies

uv add requests rich typer

5. Run Code in the Environment

uv run python main.py

Or launch an interactive shell:

uv venv shell

6. Optional: Use `direnv` for Auto-Activation

Install:

sudo pacman -S direnv

Add to your ~/.config/fish/config.fish:

eval (direnv hook fish)

Then in your project:

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:

uv add --dev black ruff ipython

🧪 Sample Project Workflow

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. 🐍🚀

Hatch Vs Poetry