Python Setup Guide - CodeSwordsman

Configure Python: the Windows installer and py launcher, managing versions with pyenv or uv, virtual environments, pip mirrors, scaffolding and common error fixes.

Python 3.11 / 3.12Updated 2026-10-2928 commands

Install & Version Management

Install Python 3.12 on Windows; the installer also ships the py launcher

winget install Python.Python.3.12

When using the official installer, tick Add python.exe to PATH or the python command will not exist

Install a specific version plus the venv module via Homebrew on macOS or apt on Ubuntu

# macOS
brew install python@3.12
# Ubuntu / Debian
sudo apt update && sudo apt install -y python3.12 python3.12-venv python3-pip

List every installed Python version and its path on Windows

py -0p

With multiple versions installed, pick one explicitly with py -3.11 or py -3.12

Install uv with pipx; uv manages Python versions, virtualenvs and dependencies much faster than pip

pip install --user pipx
pipx install uv

Install and list Python versions with uv, no admin rights required

uv python install 3.12
uv python list

Mirrors & Proxy

Switch pip to the Tsinghua mirror globally and confirm the config

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config list

Use a mirror for this install only without touching global config

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

Trust the host when an intranet mirror uses HTTP or a self-signed certificate

pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

Route pip through a proxy with environment variables on macOS/Linux; use set on Windows

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

uv accepts an index URL per install; set UV_INDEX_URL to apply it globally

uv pip install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

Environment & Virtualenv

Create and activate a project-local virtualenv so global packages stay clean

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

Use one .venv per project and add .venv/ to .gitignore

Confirm which interpreter the shell uses; after activation it should point into .venv

where python
# macOS / Linux
which python3

Enable UTF-8 mode to avoid mojibake when reading and writing Chinese text on Windows

# Windows PowerShell（永久）
[Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User")
# macOS / Linux
echo 'export PYTHONUTF8=1' >> ~/.zshrc

Leave the current virtualenv and return to the system interpreter

deactivate

Create & Verify

Verify the interpreter and pip point to the same environment, then list installed packages

python --version
pip --version
pip list

Create a minimal project, install a dependency and verify the import works

mkdir demo && cd demo
python -m venv .venv
pip install requests
python -c "import requests; print(requests.__version__)"

Export and restore the dependency list for handover and deployment

pip freeze > requirements.txt
pip install -r requirements.txt

Init a project, add dependencies and run with uv without activating a virtualenv manually

uv init demo
cd demo
uv add requests
uv run main.py

Spin up a throwaway static server to preview generated pages

python -m http.server 8000

IDE & Plugins

Install the Python extension, Pylance and Ruff for formatting and linting

code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension charliermarsh.ruff

Install formatter and type checker CLIs so CI can run the same checks

pip install ruff black mypy

Install and start JupyterLab when you need interactive analysis

pip install jupyterlab
jupyter lab

Troubleshooting

Allow local scripts when PowerShell blocks Activate.ps1, then activate the virtualenv again

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Upgrade pip through python -m pip so it lands in the right environment

python -m pip install --upgrade pip

Upgrade the build toolchain before retrying when packages with native code fail to build

pip install --upgrade pip setuptools wheel

Work through the interpreters visible on PATH when you hit command not found

where python3
where py

Clear the pip cache when downloads are corrupt or disk usage is too high

pip cache purge

Check for version conflicts among installed dependencies

pip check

Related tools

Regex Tester Code Formatter