Master Python Project Setup: From Git Init to uv Automation

How to start a Python project from zero? Follow this typical workflow:

Initialize a local Git repository with git init .

Create a remote GitHub repository and link it.

Commit the initial code using git add and git commit .

Git and GitHub Repository

Set up the repository and push your code to GitHub.

Virtual Environment

Activate a virtual environment:

Windows: .\venv\Scripts\activate

Linux/macOS: source .venv/bin/activate

Create the environment with python -m venv venv and then activate it.

Using Pyenv

Manage Python versions with Pyenv and set the project version:

<code>pyenv local 3.12.0</code>

Using Poetry

Initialize and manage the project with Poetry:

poetry init

poetry install

Create a virtual environment and set Python version using poetry shell and poetry env use 3.12.0

Configuration Files

Create a .gitignore to exclude unwanted files.

Create a .env to store environment variables (do not commit).

Why Try uv?

uv combines the functionality of pip, Poetry, pyenv, and virtualenv, and is 10‑100× faster than pip, dramatically reducing dependency‑management time.

Installation

Install uv using one of the following methods:

Linux/macOS: <code>curl -LsSf https://astral.sh/uv/install.sh | sh</code>

Windows (PowerShell): <code>irm https://astral.sh/uv/install.ps1 | iex</code>

Key project files include .python-version , hello.py , pyproject.toml , and README.md .

Using uv

Install uv via pip if preferred:

<code>pip install uv</code>

Initialize a new project:

<code>uv init</code>

This creates four files: .gitignore , .env , pyproject.toml , and README.md .

Virtual Environment

Create and activate a virtual environment:

<code>uv venv</code>

<code>. venv/Scripts/activate</code>

Adding Dependencies

Add packages easily:

uv add typer

uv add pytest --dev (development dependency)

uv add fastapi jupyter pandas (multiple packages)

Remove a package:

<code>uv remove fastapi</code>

Running

Run tests with:

<code>uv run pytest</code>

Execute a script such as hello.py :

<code>uv run .\hello.py</code>

Managing Python Versions

Check the current Python version:

<code>uv run python --version</code>

Install specific Python versions:

<code>uv python install 3.12.3</code>

<code>uv python install 3.9 3.10 3.11</code>

Recreate a virtual environment with a chosen Python version:

<code>uv venv --python 3.12.3</code>

Or sync the environment:

<code>uv sync</code>

Using Ruff for Code Formatting

Check code style:

<code>uv run ruff check</code>

Format code automatically:

<code>uv run ruff format</code>

Ruff is a fast Python linter and formatter that helps keep the codebase clean and consistent.

Conclusion

These are the basic commands and features of uv. For more details, refer to the official documentation.