Production-Ready Python Setup on macOS (Strict, Typed, Clean)

Joe Kulandy

joe@kulandy.com

Published on February 24, 2026

This guide explains how to set up a production-ready Python development environment on macOS using Homebrew, virtual environments, Ruff, Black, mypy in strict mode, pytest, and Git with pre-commit hooks.

The objective is to create a disciplined, maintainable, and scalable Python setup suitable for backend systems, AI pipelines, and long-term software projects.

Many Python tutorials focus on getting started quickly. This guide focuses on engineering discipline. It emphasizes strict static typing, automated linting, formatting consistency, and enforced commit checks.

If you are building serious Python systems, especially in AI and backend development, this setup provides a clean and reproducible foundation.

After years of building web applications, I am now spending more time in Python. Especially in backend systems and AI-oriented work.

I did not want a casual setup. I wanted something strict. Typed. Clean. Enforced.

This is the exact Python environment I use on macOS. It is simple, but disciplined. It includes:

  • Homebrew-managed Python
  • Isolated virtual environments
  • Ruff for fast linting
  • Black for consistent formatting
  • Mypy in strict mode
  • Pre-commit hooks for enforcement
  • Clean Git workflow

If you are serious about writing production-grade Python, this setup will help you avoid future mess.

Production-ready Python development workflow on macOS with virtual environments, Ruff, Black, mypy strict mode, pytest, and Git pre-commit hooks

Production-ready Python development workflow on macOS with strict typing, linting, testing, and Git automation.

Why Use Strict Typing in Python for Production Systems?

Python is flexible. That flexibility is powerful. But in larger systems, it can become dangerous.

When projects grow, small type mistakes become runtime bugs. Those bugs are harder to trace. Especially in backend systems and AI pipelines where data flows through multiple layers.

Strict typing forces clarity. It makes function contracts explicit. It reduces ambiguity. It prevents entire classes of runtime errors before execution.

Using mypy in strict mode adds discipline:

  • No untyped function definitions
  • No silent optional values
  • No hidden "Any" types leaking into the system
  • Clear and maintainable interfaces

In short, strict typing makes Python behave more like an engineered system, not a scripting language.

For long-term maintainability, especially in AI-heavy logic, this matters.

If you are working with structured data or graph-based systems, you may also find my deep dive on Graph Traversal Algorithms in Python using BFS and DFS with NetworkX useful. It explores algorithmic foundations that often appear in real-world backend and AI workflows.

How to Install Homebrew and Python 3.12+ on macOS

I do not use the system Python that comes with macOS. It is tied to the operating system and should not be modified.

Instead, I install Python using Homebrew. This keeps development tools isolated from system dependencies.

Python documentation: Official Python 3 Documentation.

Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Add Homebrew to your PATH:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

How to Create a Python Virtual Environment on macOS

brew install python

Verify the installation:

which python3
python3 --version

You should see something like:

/opt/homebrew/bin/python3
Python 3.12+

This ensures your development Python is separate from /usr/bin/python3.

How to Install VSCode on macOS for Python Development

Download from: https://code.visualstudio.com/

Enable CLI:

Cmd + Shift + P
Shell Command: Install 'code' command in PATH

How to Organize a Python Project Folder Structure on macOS

I keep all development projects inside a dedicated directory. This keeps my machine organized and scalable over time.

Create a Development Workspace

mkdir -p ~/Developer
~/Developer/
    personal/
    clients/
    experiments/

This separation helps long-term maintainability and mental clarity.

How to Create a New Python Project

cd ~/Developer
mkdir myproject
cd myproject
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

I always use virtual environments. This prevents global package pollution and keeps dependencies isolated per project.

To verify the environment:

which python
python --version

The path should point to .venv/bin/python.

How to Configure VSCode for Python Development

I use Visual Studio Code for Python development. The key is to let VSCode detect the virtual environment instead of manually hardcoding interpreter paths.

Open the Project Folder (Not a Single File)

code .

The dot is important. It tells VSCode that this folder is the workspace.

Select the Python Interpreter

Open Command Palette:

Cmd + Shift + P
Python: Select Interpreter
Choose .venv/bin/python

Do not manually set:

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

Modern VSCode automatically detects .venv. Manual configuration is unnecessary and may cause startup warnings.

Recommended Extensions

  • Python (Microsoft)
  • Ruff
  • Black Formatter
  • Mypy Type Checker

How to Install and Configure Ruff, Black, Pytest, and Mypy

Once the virtual environment is activated, I install all development tools inside it. I never install these globally.

pip install ruff black pytest pre-commit mypy

Each tool has a clear purpose:

  • Ruff - Fast linting and code quality checks
  • Black - Opinionated, consistent code formatting
  • Pytest - Simple and powerful testing framework
  • Mypy - Static type checking in strict mode
  • Pre-commit - Enforces rules before every commit

This combination keeps the codebase disciplined and consistent.

Ruff configuration details are available in the official Ruff documentation.

Black formatting guidelines can be found in the official Black documentation.

How to Configure pyproject.toml for Strict Python Typing

I centralize tool configuration inside pyproject.toml. This keeps the project clean and avoids scattered config files.

Create a file named pyproject.toml in the project root.

[tool.ruff]
line-length = 88
target-version = "py312"
select = ["E", "F", "I", "B"]
fix = true

[tool.black]
line-length = 88
target-version = ["py312"]

[tool.mypy]
python_version = "3.12"
strict = true
warn_unused_ignores = true
warn_redundant_casts = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_any_generics = true
no_implicit_optional = true
check_untyped_defs = true

[tool.pytest.ini_options]
testpaths = ["tests"]

What This Does

  • Enforces consistent formatting (Black)
  • Runs fast lint checks (Ruff)
  • Forces strict static typing (Mypy)
  • Standardizes test discovery (Pytest)

The strict = true setting in mypy turns Python into a disciplined, strongly checked environment. This is intentional.

For full strict configuration options, refer to the official mypy documentation.

How to Run Mypy in Strict Mode for Type Safety

With strict mode enabled, every function must be clearly typed. This improves readability and prevents hidden runtime errors.

Create a simple example inside src/myproject/main.py:

def add(a: int, b: int) -> int:
    return a + b

Because mypy is in strict mode:

  • Every parameter must have a type
  • Return types must be explicit
  • Implicit Any types are not allowed

Run Type Checking

mypy src/

If types are incorrect, mypy will fail before runtime. This shifts error detection earlier in the development cycle.

In larger backend systems or AI pipelines, this reduces subtle bugs that only appear under specific data conditions.

This kind of disciplined environment becomes especially important when building AI-driven features. For example, in my article on building an AI-powered spam detection layer using the ChatGPT API, strict typing and structured validation significantly reduce integration errors.

How to Initialize a Git Repository for a Python Project

Every serious project should be version controlled from day one. I initialize Git immediately after creating the project.

git init

Create .gitignore

It is important to ignore environment files and caches.

.venv/
__pycache__/
.pytest_cache/
.vscode/
.mypy_cache/

This prevents unnecessary files from being committed.

Initial Commit

git add .
git commit -m "Initial strict typed project setup"

This establishes a clean baseline before development begins.

How to Connect a Local Python Project to GitHub

Once the local repository is initialized, I connect it to a remote repository. This provides backup, collaboration, and CI integration.

Create a Repository on GitHub

Create a new repository on GitHub. Do not initialize it with a README if your project already exists locally.

Add the Remote

git remote add origin https://github.com/yourusername/myproject.git

Rename the branch to main (if necessary):

git branch -M main

Push the initial commit:

git push -u origin main

I have applied similar engineering discipline in real-world systems, such as my guide on real-time energy tracking using Python, PHP, and Google Cloud, where backend reliability and data integrity were critical.

Optional: Use SSH Instead of HTTPS

For a more professional setup, use SSH.

ssh-keygen -t ed25519 -C "your-email@example.com"
cat ~/.ssh/id_ed25519.pub

Add the public key to GitHub under Settings → SSH Keys.

Then update the remote:

git remote set-url origin git@github.com:yourusername/myproject.git

Using SSH avoids repeated authentication prompts.

How to Use Pre-commit Hooks with Ruff, Black, and Mypy

Manual discipline is unreliable. Automation is better.

I use pre-commit to automatically run linting, formatting, and type checking before every commit.

Create .pre-commit-config.yaml

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      - id: ruff
        args: ["--fix"]

  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy

Install the Hooks

pre-commit install

From this point onward, every git commit will:

  • Run Ruff (and auto-fix issues)
  • Format code with Black
  • Run Mypy in strict mode

If something fails, the commit is blocked. This keeps the repository clean by default.

Pre-commit framework documentation: pre-commit.com.

Daily Workflow for a Production-Ready Python Environment

Once everything is configured, the workflow becomes simple and consistent.

source .venv/bin/activate
ruff check .
black .
mypy src/
pytest
git add .
git commit -m "clean strict commit"
git push

In most cases, pre-commit handles Ruff, Black, and Mypy automatically during commit. Running them manually is optional but useful during development.

Frequently Asked Questions

What is a production-ready Python environment?

A production-ready Python environment includes isolated virtual environments, strict static typing with mypy, automated linting, consistent formatting, test integration, and enforced Git workflows. It is designed for maintainability and scalability.

Why use mypy in strict mode?

Mypy strict mode enforces explicit type annotations, prevents implicit Any types, and reduces runtime type errors. It improves code clarity and long-term maintainability, especially in backend and AI systems.

Is Ruff better than flake8?

Ruff is significantly faster than flake8 and consolidates multiple linting tools into one. It supports automatic fixes and simplifies Python project configuration.

Should I use virtual environments on macOS?

Yes. Virtual environments isolate project dependencies and prevent conflicts between Python packages. They are essential for clean and reproducible development workflows.

Do I need pre-commit hooks for small projects?

Even in small projects, pre-commit hooks help maintain code quality automatically. They ensure formatting, linting, and type checks run before every commit.

Result

  • Homebrew Python
  • Isolated virtual environments
  • Lint enforcement with Ruff
  • Automatic formatting with Black
  • Pytest testing
  • Strict static typing with mypy
  • Pre-commit quality enforcement
  • Remote Git integration

This is production-grade, enterprise-ready Python setup.

This foundation becomes especially valuable when building AI systems, data pipelines, or backend APIs where type safety and reproducibility are critical.

It is not about adding complexity. It is about reducing future risk.

As I move deeper into backend systems and AI-driven applications, I prefer engineering clarity over convenience.

If you are building serious Python systems, start with a disciplined foundation.

Home | joe@kulandy.com