--- title: "Python Virtual Environments Cheatsheet" description: "A practical reference for venv, pip, requirements files, pyenv version switching, and pipx for isolated global tools." author: "Mohammad Abu Mattar" canonical: https://mkabumattar.com/cheatsheets/python-venv --- # Python Virtual Environments Cheatsheet A fast reference for keeping Python projects isolated and reproducible. It covers creating and activating environments with venv, installing packages with pip, locking dependencies with requirements files and pip-tools, switching interpreter versions with pyenv, and installing global CLI tools cleanly with pipx. ## Creating and Activating Environments Make an isolated environment per project so dependencies never collide. ### Create a virtual environment Use the built-in venv module to create an isolated environment in a project folder. **Keywords:** venv, create, virtualenv #### Create an environment named .venv ```bash python -m venv .venv ``` Creates a self-contained Python environment in the .venv folder, with its own interpreter and site-packages. - Name it .venv by convention so editors and tools auto-detect it. - Add .venv/ to your .gitignore; never commit an environment. #### Create with a specific interpreter ```bash python3.12 -m venv .venv ``` Uses whichever Python you invoke as the base for the environment, which is how you pin the version. ### Activate and deactivate Activating puts the environment's interpreter and pip first on your PATH. **Keywords:** activate, deactivate, source #### Activate on macOS or Linux ```bash source .venv/bin/activate ``` Your prompt gains a (.venv) prefix and python/pip now point inside the environment. #### Activate on Windows ```powershell .venv\Scripts\Activate.ps1 ``` PowerShell activation. Use .venv\Scripts\activate.bat from cmd.exe instead. #### Deactivate ```bash deactivate ``` Restores your original PATH. Works from any shell where the environment is active. **Best practices:** - Confirm activation with `which python` (it should point inside .venv). - You do not have to activate: `.venv/bin/python script.py` works directly, which is handy in scripts and CI. ### Remove an environment Environments are disposable; delete and recreate rather than repairing. #### Delete the environment ```bash rm -rf .venv ``` There is no uninstall command. The environment is just a folder, so removing it is the reset. ## Installing Packages with pip Install, upgrade, and inspect packages inside the active environment. ### Install packages pip installs into whichever environment is currently active. **Keywords:** pip, install, upgrade #### Install a package ```bash pip install requests ``` #### Install a specific version ```bash pip install 'django==5.0.*' ``` Quote version specifiers so the shell does not interpret the characters. #### Editable install of a local project ```bash pip install -e . ``` Links your source in place so code changes take effect without reinstalling. This is the usual setup while developing a package. **Common errors:** - **pip installs globally instead of into the environment**: You forgot to activate. Check `which pip`, then re-run after activating .venv. ### Inspect installed packages See what is installed and whether anything is outdated. #### List installed packages ```bash pip list ``` #### Show outdated packages ```bash pip list --outdated ``` ## Managing Dependencies Capture and restore your dependency set so environments are reproducible. ### requirements.txt Freeze the current environment and restore it elsewhere. **Keywords:** requirements.txt, freeze, reproducible #### Freeze current dependencies ```bash pip freeze > requirements.txt ``` Writes every installed package and its exact version so others can reproduce the environment. #### Install from requirements.txt ```bash pip install -r requirements.txt ``` **Best practices:** - pip freeze captures everything, including transitive dependencies, which makes it noisy. Keep your true top-level deps in a separate file. ### Deterministic installs with pip-tools Separate the packages you ask for from the fully pinned set you install. **Keywords:** pip-tools, pip-compile, lockfile #### Compile a locked requirements file ```bash # list only top-level deps in requirements.in, then: pip-compile requirements.in ``` Produces a fully pinned requirements.txt (including transitive deps and hashes) from your short requirements.in. #### Sync the environment to the lockfile ```bash pip-sync requirements.txt ``` Installs exactly what the lockfile says and removes anything that is not in it, so the environment matches the lock precisely. **Advanced notes:** - **Why pip-compile over plain freeze:** requirements.in records intent (the packages you actually want), while the compiled output records the exact resolved graph. Editing intent and recompiling is far cleaner than hand-editing a frozen dump. ## Switching Python Versions with pyenv Install and switch between multiple Python versions per machine or per project. ### Install and select versions pyenv manages the Python interpreter itself, independently of your OS Python. **Keywords:** pyenv, versions, global, local #### Install a Python version ```bash pyenv install 3.12.4 ``` #### Set the global default ```bash pyenv global 3.12.4 ``` #### Pin a version for one project ```bash pyenv local 3.11.9 ``` Writes a .python-version file so this directory always uses that interpreter. ### pyenv-virtualenv Combine a pyenv-managed version with a named virtual environment. #### Create a named environment on a chosen version ```bash pyenv virtualenv 3.12.4 myproject-3.12 ``` Creates a virtual environment tied to a specific pyenv Python, which you can then activate by name or auto-activate with pyenv local. ## Global CLI Tools with pipx Install Python command-line tools globally without polluting any project environment. ### Install and run tools pipx gives each tool its own hidden environment while exposing its command on your PATH. **Keywords:** pipx, global, isolation #### Install a CLI tool ```bash pipx install ruff ``` Installs ruff in its own isolated environment but makes the ruff command available everywhere. #### Run a tool once without installing ```bash pipx run cowsay moo ``` Downloads into a temporary environment, runs the command, and cleans up. Handy for a tool you need once. **Best practices:** - Use pipx for tools (black, ruff, httpie, poetry), and venv for project libraries. Never pip install CLI tools into your system Python.