How to set up a development environment for Python with virtualenv/venv and dependency management
Setting up a clean Python development environment helps you avoid package conflicts and makes projects reproducible. This guide walks through creating isolated environments with venv or virtualenv, installing and recording dependencies, and keeping things portable for collaborators or deployment.
Step 1: Install Python 3 and pip
Ensure Python 3.8 or newer is installed on your machine and that pip is available. Verify by running python3 --version and python3 -m pip --version; if missing, install from your OS package manager or python.org so you have a stable baseline for virtual environments.
[Illustration: Terminal window showing python3 --version and pip --version outputs]
Step 2: Choose venv or virtualenv
Decide between the standard library venv or the third-party virtualenv; venv is included and fine for most projects, while virtualenv can be faster and supports older Pythons. Install virtualenv with python3 -m pip install --user virtualenv if you need its features and want isolation from system packages.
[Illustration: Two icons labeled venv and virtualenv with a checkmark near venv]
Step 3: Create the environment
Create a new environment inside your project folder. From the project root run python3 -m venv .venv or python3 -m virtualenv .venv; this produces a .venv directory that isolates interpreter and packages for predictable behavior across machines.
[Illustration: File tree showing project/ and project/.venv/ directories]
Step 4: Activate the environment
Activate the virtual environment before installing packages: source .venv/bin/activate on macOS/Linux or .venv\Scripts\activate on Windows PowerShell. Activation ensures python and pip map to the environment so you don't pollute the system Python.
[Illustration: Terminal with a prompt prefixed by (.venv) indicating activation]
Step 5: Install and pin dependencies
Install packages with pip install package==x.y.z to pick exact versions, or pip install -r requirements.txt to bulk-add. After installing, run pip freeze > requirements.txt to record exact versions so others can reproduce your environment in about a minute.
[Illustration: Terminal running pip install and pip freeze > requirements.txt commands]
Step 6: Use development dependency workflow
Separate runtime and dev tools by using dev-requirements.txt or a tool like pip-tools; install test and lint tools with pip install -r dev-requirements.txt. This keeps production deployments lean and local developer workflows faster by limiting install scope to about 5–10 dev packages typically.
[Illustration: Two files side by side labeled requirements.txt and dev-requirements.txt]
Step 7: Keep environments out of version control
Add .venv/ to .gitignore and do not commit the actual virtual environment or installed packages. Instead commit requirements.txt and a short README with setup steps so a collaborator can recreate the env in 1–2 minutes using python3 -m venv .venv && .venv/bin/pip install -r requirements.txt.
[Illustration: Git ignore file listing .venv next to a README and requirements.txt]
- Use python3 -m pip rather than plain pip to guarantee the right interpreter is used.
- Consider using pip-tools or poetry to manage dependency resolution and keep requirements stable; try pip-compile once per week or per dependency change.
- Upgrade pip inside the env with python -m pip install --upgrade pip setuptools wheel to avoid build errors; do this immediately after activation, about 30 seconds.
- For frequent context switching, create one .venv per project; creating a new venv takes 1–2 seconds to initialize and avoids cross-project breakage.
- Use virtual environment names like .venv or venv to make scripts and CI predictable; many CI systems ignore dot-folders by configuration.
- Document the exact Python minor version (e.g., 3.10) in your README so teammates use the same interpreter when recreating the environment.
- Do not commit the .venv directory to version control — it can add hundreds of megabytes and cause merge noise.
- Avoid installing packages globally with sudo pip install — that can break system tools and create hard-to-debug conflicts.
- When pinning packages, be careful with broad version ranges; using loose pins can lead to ‘works on my machine’ issues during deployment.
- Be mindful of compiled wheels and native dependencies; some packages need system libraries (e.g., libpq-dev) and will fail unless the OS-level dependencies are installed.
Was this guide helpful?
More Computers & Electronics guides
How to set up Git, create a repository, and commit code locally
Setting up Git and committing code locally is a small, reliable skill that pays off immediately. In about 10–20 minutes you can install Git, create a repository, and make your first commits so your work is tracked and easy to manage. Follow these clear steps to get a solid local workflow going.
How to migrate email from one provider to another without losing folders or contacts
Migrating email between providers can feel risky, but with a plan you can preserve folders, labels, and contacts while minimizing downtime. This guide walks you through a careful, step-by-step transfer you can complete in a few hours to a couple days depending on mailbox size. Follow the checklist and you’ll keep structure and address data intact.
How to clean dust and replace a laptop fan to fix overheating and throttling
Overheating and CPU/GPU throttling are often caused by dust buildup or a failing fan. This guide walks you through safely cleaning dust and replacing a laptop fan to restore cooling performance and reduce temperature spikes. Read through all steps, gather basic tools, and work in a well-lit, static-safe area.