Skip to content

Python Development Environment Setup

A fully configured Python development environment with an isolated virtual environment, working pip, a project directory structure, and an editor pointed at the right interpreter. These steps work for any project — scripts, web services, data pipelines, or ML experiments.

  • Python 3.9+ installed (install guide)
  • A terminal (PowerShell, bash, or zsh)
  • VS Code or PyCharm (optional but recommended)
Terminal window
mkdir orders-portal
cd orders-portal

Keep the project name lowercase with hyphens (orders-portal), not underscores or CamelCase. The directory name is not the Python package name — that comes later.

Terminal window
python -m venv .venv

This creates a .venv/ directory containing a copy of the Python interpreter and an isolated site-packages directory. Packages you install here do not affect other projects or the system Python.

Why .venv? The leading dot makes the directory hidden on Unix systems, and the name is a de facto community convention understood by editors and tools.

Step 3 — Activate the virtual environment

Section titled “Step 3 — Activate the virtual environment”
Terminal window
# Windows PowerShell
.venv\Scripts\Activate.ps1
# Windows Command Prompt
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

After activation, your prompt shows the environment name (e.g. (.venv) $). All python and pip commands now use the venv’s copies, not the system ones.

Verify:

Terminal window
python -c "import sys; print(sys.executable)"
# Should show a path inside .venv/

Step 4 — Upgrade pip and install base tools

Section titled “Step 4 — Upgrade pip and install base tools”
Terminal window
python -m pip install --upgrade pip setuptools wheel

This ensures the packaging infrastructure is current. Some packages fail to install cleanly on old pip or setuptools versions.

Terminal window
python -m pip install requests httpx pydantic

For a web service:

Terminal window
python -m pip install fastapi uvicorn[standard]

For data work:

Terminal window
python -m pip install pandas numpy matplotlib

For reproducible installs across machines and CI:

Terminal window
python -m pip freeze > requirements.txt

This writes the exact version of every installed package. Commit requirements.txt to source control.

Restoring an environment from requirements.txt:

Terminal window
python -m venv .venv
source .venv/bin/activate # or Windows equivalent
python -m pip install -r requirements.txt

A typical small project:

orders-portal/
├── .venv/ # virtual environment (not committed)
├── .gitignore
├── requirements.txt
├── README.md
├── orders_portal/ # your package (underscores, not hyphens)
│ ├── __init__.py
│ ├── main.py
│ └── utils.py
└── tests/
├── __init__.py
└── test_main.py

The package directory (orders_portal/) uses underscores because it is a Python identifier. The project directory (orders-portal/) uses hyphens because it is a filesystem path.

.venv/
__pycache__/
*.pyc
*.pyo
.env
.pytest_cache/
dist/
build/
*.egg-info/

Never commit .venv/ or .env. The virtual environment can be recreated from requirements.txt; the .env file contains secrets.

VS Code:

  1. Install the Python extension.
  2. Open the command palette (Ctrl+Shift+P) → Python: Select Interpreter → choose the .venv/Scripts/python.exe (Windows) or .venv/bin/python (macOS/Linux).
  3. VS Code will now use the venv for IntelliSense, linting, and running files.

Create .vscode/settings.json to persist the selection for the project:

{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"
}

PyCharm:

  1. Open the project folder.
  2. Go to Settings → Project → Python Interpreter → Add Interpreter → Existing.
  3. Navigate to .venv/Scripts/python.exe (Windows) or .venv/bin/python (macOS/Linux).
Terminal window
python -m pip install ruff

ruff is a fast linter and formatter that covers the roles previously split across flake8, isort, and black. Add to pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py314"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]

Run:

Terminal window
ruff check . # lint
ruff format . # format
ruff check --fix . # auto-fix lint issues
  • Not activating the venv before running scripts. Check that python -c "import sys; print(sys.executable)" shows a .venv path.
  • Committing .venv/ to source control. It is large, platform-specific, and entirely reproducible from requirements.txt.
  • Using bare pip instead of python -m pip. Bare pip may resolve to a different Python installation on the PATH.
  • Installing packages globally. Packages installed globally affect every project on the machine. Always create a venv first.
  • Not freezing dependencies before shipping. requirements.txt without pinned versions produces different installs on different days.