Python .venv setup
Keep your projects clean, isolated, and under control.
The long-short of it
Global installs bleed. Projects break.
Use a virtual environment. Isolate everything.
Not for hygiene — for integrity. And discipline.
The problem
System Python is the wild west — global packages, invisible conflicts, accidental breakage. Run enough projects on one machine, and something will break. Quietly.
You don’t know what’s in there.
And that’s the problem.
Every Python project needs a virtual environment.
Not because it’s neat. Because it’s necessary.
A virtual environment is the one part of the stack you control.
You built it. You own it. You trust it.
Use one. Always. No exceptions.
What Is Sandboxing?
A virtual environment is a sandbox — an isolated workspace where your project runs without touching anything else on your system.
No bleed. No surprise upgrades. No shared-state chaos.
It keeps your dependencies contained — and your results stable.
Why virtual environments matter
When you install packages globally, they bleed across projects.
One “simple upgrade” — now half your scripts throw errors.
Why?
Because something changed. Somewhere. Silently.
That’s not progress. That’s drift — the quiet kind, where environments mutate and your code stops behaving the way it used to.
A virtual environment locks your project in place — clean, isolated, reproducible.
No silent updates. No hidden conflicts. No surprises.
It’s not about security. It’s about integrity.
If your environment isn’t isolated, your results aren’t reproducible.
And reproducibility is everything.
The setup — macOS
Here’s how I run every Python project.
Fast. Repeatable. No guesswork.
1. Get in position
Open your terminal and navigate to your project folder:
cd /path/to/your/projectIf your folder is on the desktop:
cd ~/desktop/projectConfirm you’re in the right place:
pwdExpected output:
/Users/you/desktop/project2. Build the sandbox
Create the virtual environment inside your project folder:
python3 -m venv .venvThat creates a hidden folder called .venv.
It holds your packages — and keeps them out of your global Python setup.
3. Activate the environment
Activate the virtual environment so you can install what you need:
source .venv/bin/activateYou’ll know it worked when the prompt changes:
(.venv) you@computer project % 4. Upgrade pip
Always upgrade pip — the default is usually stale:
pip install --upgrade pip5. Install what you need
Check the current environment:
pip listYou’ll just see pip to start:
Package Version
------- -------
pip 25.1Install your packages:
pip install pandas plotly kaleidoCheck what’s now installed:
pip listYou’ll see more than your packages as their dependencies get installed too:
Package Version
--------------- -----------
kaleido 0.2.1
narwhals 1.37.1
numpy 2.2.5
packaging 25.0
pandas 2.2.3
pip 25.1
plotly 6.0.1
python-dateutil 2.9.0.post0
pytz 2025.2
six 1.17.0
tzdata 2025.26. Lock the environment
Freeze the environment into a requirements file:
pip freeze > requirements.txtThis captures both your packages and their dependencies:
# requirements.txt
kaleido==0.2.1
narwhals==1.37.1
numpy==2.2.5
packaging==25.0
pandas==2.2.3
plotly==6.0.1
python-dateutil==2.9.0.post0
pytz==2025.2
six==1.17.0
tzdata==2025.27. Rebuild anywhere
Recreate the same environment on another machine using the requirements.txt file:
pip install -r requirements.txtSame setup. Same results.
8. Shut it down
When you’re done:
deactivateThis exits the virtual environment and returns you to system Python.
This is your .venv
No conflicts. Just code you can trust.
Clean installs.
Reproducible environments.
Zero cross-contamination.
Total control.
This isn’t about neatness.
It’s about knowing exactly what your code is running on.
Your Python environment is part of your edge.
Treat it like one.
Know someone still installing into system Python?
Share this before their environment breaks something that matters.