Python Development Environment Setup
What you’ll build
Section titled “What you’ll build”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.
Prerequisites
Section titled “Prerequisites”- Python 3.9+ installed (install guide)
- A terminal (PowerShell, bash, or zsh)
- VS Code or PyCharm (optional but recommended)
Step 1 — Create a project directory
Section titled “Step 1 — Create a project directory”mkdir orders-portalcd orders-portalKeep the project name lowercase with hyphens (orders-portal), not underscores or CamelCase. The directory name is not the Python package name — that comes later.
Step 2 — Create a virtual environment
Section titled “Step 2 — Create a virtual environment”python -m venv .venvThis 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”# Windows PowerShell.venv\Scripts\Activate.ps1
# Windows Command Prompt.venv\Scripts\activate
# macOS / Linuxsource .venv/bin/activateAfter 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:
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”python -m pip install --upgrade pip setuptools wheelThis ensures the packaging infrastructure is current. Some packages fail to install cleanly on old pip or setuptools versions.
Step 5 — Install your dependencies
Section titled “Step 5 — Install your dependencies”python -m pip install requests httpx pydanticFor a web service:
python -m pip install fastapi uvicorn[standard]For data work:
python -m pip install pandas numpy matplotlibStep 6 — Pin dependencies
Section titled “Step 6 — Pin dependencies”For reproducible installs across machines and CI:
python -m pip freeze > requirements.txtThis writes the exact version of every installed package. Commit requirements.txt to source control.
Restoring an environment from requirements.txt:
python -m venv .venvsource .venv/bin/activate # or Windows equivalentpython -m pip install -r requirements.txtStep 7 — Project layout
Section titled “Step 7 — Project layout”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.pyThe 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.
Step 8 — Add a .gitignore
Section titled “Step 8 — Add a .gitignore”.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.
Step 9 — Configure your editor
Section titled “Step 9 — Configure your editor”VS Code:
- Install the Python extension.
- Open the command palette (
Ctrl+Shift+P) → Python: Select Interpreter → choose the.venv/Scripts/python.exe(Windows) or.venv/bin/python(macOS/Linux). - 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:
- Open the project folder.
- Go to Settings → Project → Python Interpreter → Add Interpreter → Existing.
- Navigate to
.venv/Scripts/python.exe(Windows) or.venv/bin/python(macOS/Linux).
Step 10 — Add linting and formatting
Section titled “Step 10 — Add linting and formatting”python -m pip install ruffruff 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 = 100target-version = "py314"
[tool.ruff.lint]select = ["E", "F", "I", "N", "W"]Run:
ruff check . # lintruff format . # formatruff check --fix . # auto-fix lint issuesCommon mistakes
Section titled “Common mistakes”- Not activating the venv before running scripts. Check that
python -c "import sys; print(sys.executable)"shows a.venvpath. - Committing
.venv/to source control. It is large, platform-specific, and entirely reproducible fromrequirements.txt. - Using bare
pipinstead ofpython -m pip. Barepipmay 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.txtwithout pinned versions produces different installs on different days.
Next steps
Section titled “Next steps”- Modules and packages — how Python finds modules;
__init__.py; relative imports - Python tools overview — when to use uv, poetry, or pipenv instead of plain pip
- Python basics quick reference — syntax at a glance