Python

Python is a popular general-purpose programming language that is especially suited to web development.

Install Python

Debian/Ubuntu

sudo apt update -y
sudo apt -y install python3
sudo apt -y install python3-venv

macOS

brew install python@3.14
brew unlink python@3.14 && brew link python@3.14 --force --overwrite

Check Python installation

python --version

In some cases, old Python version can take priority on new version:

Python 3.9.6

output

Here a solution for macOS with Homebrew:

TIP

Adapt path if your OS is Linux.

export PATH="/opt/homebrew/opt/python@3.14/bin:$PATH"

~/.zshrc

Reload your PATH:

source ~/.zshrc
python --version

Now Python v3.14 by Homebrew will be used. If not works, check where is your Python version:

which python3
# OR
which python

Install uv

uv is an extremely fast Python package and project manager, written in Rust.

This replaces pip, but more importantly, this CLI allows for better management of Python environments. In the rest of this guide, uv will be used, so it is recommended that you install it.

Follow these instructions:

macOS and Linux

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

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

You can now uses uv command.

Virtual environment

Global .venv

Python uses a virtual environment to run, so you only need to create it once globally:

python3 -m venv ~/.venv

And you'll need to enable it this way (and do so every time):

source ~/.venv/bin/activate

The output in your terminal will indicate that the Python environment is active:

(.venv) # <- Python ~/.venv is enabled
user@debian ~
$

output

Local .venv

Of course, a global Python environment is only recommended for installing a CLI globally, for example, but not for each individual project.

The goal is to keep each project and its dependencies isolated in order to minimize the risk of version conflicts.

Generate .venv

In each project, you can now uses uv to easily isolate your projects:

├── pyproject.toml
├── README.md
├── requirements.txt
├── src
├── tests

In this project, you can execute uv to create a local venv:

uv venv

The local Python environment has been created

Using CPython 3.12.13
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

output

The Python version depends either on the .python-version file, which takes precedence if it exists, or on the version specified in the pyproject.toml file:

3.12

.python-version

[project]
requires-python = ">=3.12"

pyproject.toml

Override

You can override these settings using these commands:

# Setup with Python 3.12
uv venv --python 3.12

# Install and setup with Python 3.12
uv python install 3.12

Package manager

To help Python to understand package manager used:

[tool.deptry.package_module_name_map]
uv = "uv"

pyproject.toml

Dependencies

To handle dependencies from pyproject.toml, like this (and lock libraries versions):

dependencies = [
  "python-dotenv",
  "httpx",
  "rich",
]

pyproject.toml

You can sync with uv:

uv sync

Cross-compatible

To handle cross-compatibility with pip for legacy:

uv export --format requirements-txt > requirements.txt

You don't have to edit manually requirements.txt, let uv override it when needed.

Now uv.lock will represents dependencies.

pyproject.toml

Full example:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mycli"
version = "0.1.0"
description = "My Python CLI"
readme = "README.md"
authors = [{ name = "Author" }]
requires-python = ">=3.12"

dependencies = [
  "python-dotenv",
  "httpx",
  "rich",
]

[project.scripts]
mycli = "mycli.app:main"

[project.optional-dependencies]
dev = ["pytest~=8.0.0", "pytest-cov", "uv>=0.5.0"]

[tool.setuptools]
package-dir = { "" = "src" }

[tool.deptry]
known_first_party = ["mycli"]

[tool.deptry.per_rule_ignores]
DEP002 = ["pytest", "pytest-cov", "uv"]

[tool.deptry.package_module_name_map]
uv = "uv"

[dependency-groups]
dev = ["pytest-cov>=7.0.0"]

Useful alias

You can add these alias to ~/.zshrc:

export PATH="/opt/homebrew/opt/python@3.14/bin:$PATH" # macOS
export PATH="$HOME/.venv/bin:$PATH" # global CLI
alias python="python3"
alias py-global="source ~/.venv/bin/activate" # global python venv
alias va="source .venv/bin/activate" # local python venv
alias ur="uv run" # shortcut for uv run

~/.zshrc

source ~/.zshrc

You can now enable local environment with va command and use ur shortcut for uv run.

ur pytest

Execute

uv run python main.py

uv and CLI

Install in edit mode (useful if you're modifying the code)

uv tool install --editable .

Update after a git pull

uv tool upgrade <cli-name>

View installed tools

uv tool list

Uninstall

uv tool uninstall <cli-name>

Tests

├── pyproject.toml
├── README.md
├── src
├── tests
│   ├── __init__.py
│   ├── book
│   │   ├── __init__.py
│   │   └── test_book.py
│   ├── pack
│   │   ├── __init__.py
│   │   ├── test_pack.py
│   │   └── test_unpack.py
│   └── test_files.py
└── uv.lock

To use pytest with uv:

[project.optional-dependencies]
dev = ["pytest~=8.0.0"]

pyproject.toml

TIP

You can allow dev dependencies to be sync:

uv sync --extra dev

Now you can execute tests:

uv run pytest

Options

You can print output with -s flag and enable verbose with -v flag:

uv run pytest -s -v

You can execute specific test

uv run pytest -s ./tests/book/test_book.py

You can execute specific method in test

uv run pytest -s ./tests/book/test_book.py

More

Check loaded venv

which python3

deptry

deptry is a command line tool to check for issues with dependencies in a Python project, such as unused or missing dependencies. It supports projects using Poetry, pip, PDM, uv, and more generally any project supporting PEP 621 specification.

uv add --dev deptry
uv run deptry .

deactivate

You can disable a virtual environment with:

deactivate

direnv

https://direnv.net/

direnv is an extension for your shell. It augments existing shells with a new feature that can load and unload environment variables depending on the current directory.

VSCode

For VSCode users, use Shift+Ctrl+P / Shift+Cmd+P and select Python: Select Interpreter to select local virtual environment, like /Workspace/project/.venv/bin/python.

Best way:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

.vscode/settings.json