Python Project Environment Setup

First PublishedMay 23, 2026ByAtif Alam

This page walks through setting up a new Python project on macOS: check or install Python, create an isolated environment, install dependencies, and pin versions when you need more than one interpreter.

Guides elsewhere in this library often use the standard library only; use this page when you need third-party packages or a pinned Python version.

Check What You Already Have

python3 --version
which python3

macOS may ship a system python3. That is fine for a quick check, but avoid using it as your only interpreter for development — system Python is meant for the OS, not your projects.

If you installed Python with Homebrew (brew install [email protected]), which python3 may point at Homebrew’s binary instead.

Install Python (if Needed)

Recommended — uv

uv installs Python versions, creates virtual environments, and manages packages in one tool.

# Option A: Homebrew (same pattern as other macOS guides in this library)
brew install uv

# Option B: official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

uv --version
uv python install 3.12
uv python list

See the uv documentation for advanced options.

Alternative — Homebrew Python Only

brew install [email protected]
python3.12 --version

Use this when you want a standalone interpreter without uv. You still create virtual environments with python3.12 -m venv (see below).

Multiple Python Versions — uv vs pyenv

You may need Python 3.11 for one repo and 3.12 for another. Two common approaches on a Mac:

Concern	uv	pyenv
Install/switch Python versions	uv python install, uv python pin, .python-version	pyenv install, pyenv local / pyenv global
Virtual env + packages	Built-in (uv venv, uv add, uv sync)	Needs venv or a plugin such as pyenv-virtualenv
Speed / modern workflow	Fast; one tool for versions and deps	Mature; shell shims; common on existing teams
Best when	New projects, greenfield Mac setup	Team already standardized on pyenv, or global shim switching across many tools

uv can manage Python versions for most new workflows — you do not need pyenv if you adopt uv end-to-end.

pyenv remains valid when your team or dotfiles already rely on it. uv and pyenv can coexist: pyenv selects which python runs in your shell; uv still speeds up installs inside a project.

Per-project pinning: uv python pin 3.12 writes a .python-version file. pyenv uses the same filename.

Do not let both tools fight over .python-version without knowing which one owns it in a given repo.

asdf fills a similar niche to pyenv (multiple runtimes, one version file). The same advice applies: pick one version manager per project.

Create a New Project (uv — Recommended)

mkdir myapp && cd myapp
uv init --python 3.12
uv venv
source .venv/bin/activate
uv add requests
uv run python -c "import requests; print(requests.__version__)"

Expected layout:

myapp/
  pyproject.toml
  .venv/
  main.py          # or src/ layout for larger apps

Add to .gitignore at minimum:

.venv/
__pycache__/
*.pyc

Some teams commit .python-version; others gitignore it. Pick one convention per repo.

Create a New Project (venv + pip)

For teams that require pip and requirements.txt:

mkdir myapp && cd myapp
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests
pip freeze > requirements.txt

pip installs packages only; it does not install Python interpreters. Use uv, Homebrew, or pyenv when you need another Python version.

Teams that pin dependencies heavily sometimes use requirements.in with pip-tools; that is optional here.

Translating Online pip Commands to uv

Most Python tutorials and docs online assume pip. If you set up with uv, use this table when you follow those instructions.

Following a tutorial that says pip install …? Use the table below — you usually do not need to install pip separately.

You See Online (pip)	With uv (Recommended)	Notes
pip install requests	uv add requests	Updates pyproject.toml and lockfile when using the uv init workflow
pip install requests==2.31.0	uv add 'requests==2.31.0'	Quote versions that contain shell metacharacters
pip install -r requirements.txt	uv pip install -r requirements.txt	Drop-in when a tutorial ships a requirements file
pip install -e .	uv pip install -e . or uv sync	Editable install for local packages
python script.py	uv run python script.py	Works without activating .venv
pip freeze > requirements.txt	Prefer uv add and a committed lockfile	uv export can emit requirements-style output if needed
pip install --upgrade pip	Skip — uv manages tooling	Not needed in a uv-managed project

Two uv modes:

1. uv add — project-native. Use when you started with uv init and want dependencies tracked in pyproject.toml.
2. uv pip install — pip-compatible shim. Use when copying commands verbatim from older docs or requirements.txt-based tutorials.

If a tutorial mixes system Python and pip, stop and use your project .venv (or uv run) instead — do not install packages into the macOS system interpreter.

Daily Workflow Cheatsheet

Task	Command
Activate env	source .venv/bin/activate
Deactivate	deactivate
Add a dependency (uv project)	uv add package-name
Add from an old tutorial	uv pip install package-name — see Translating Online pip Commands to uv
Run without activating	uv run python script.py

Verify Everything Works

With .venv activated:

which python
python --version
python -c "import sys; print(sys.prefix)"

sys.prefix should point inside your project’s .venv directory, not /usr or a system path.

Key Takeaways

• On macOS, check python3 --version first; avoid developing against the system interpreter alone.
• uv is the recommended path: install Python versions, create .venv, and manage deps with uv add or uv pip install.
• pyenv (or asdf) still fits teams already on those tools; uv can manage versions without them for new projects.
• Online docs say pip install — translate with the table above (uv add vs uv pip install).
• Confirm your active interpreter with which python and sys.prefix inside .venv.

Related Links

• Run and test your first script — hands-on next step after setup
• Language basics — types, conditionals, loops
• Examples overview — stdlib walkthroughs you can run after setup
• Python FastAPI layout — production folder layout using pyproject.toml
• CI/CD pipeline fundamentals — caching venv and dependency installs in pipelines