Create a Python virtual environment without mixing dependencies
A small, repeatable setup for a project and a quick check that pip uses the right Python.
On this page
The short answer
Create one virtual environment per project. Install packages through that environment’s Python interpreter so dependencies do not spill into another project or your system installation.
Choose Python before creating the environment
A virtual environment separates packages, but still depends on the Python used to create it. Check the project’s required Python version first. If several versions are installed, use the intended interpreter explicitly rather than assuming python selects the right one.
Create .venv from the project root. Keep your application files beside that directory, not inside it: the environment is disposable and should be recreated when the interpreter or machine changes. The commands below show a common Linux or macOS setup; on some Linux systems, venv support requires an additional operating-system package.
python3 --version
python3 -m venv .venv
source .venv/bin/activateWindows PowerShell: activation is optional
On Windows, py -m venv .venv uses the launcher’s selected Python. If the project requires a specific installed version, select it through the launcher, for example py -3.12 -m venv .venv. Activate with the PowerShell command below.
If script execution policy blocks activation, you can use the environment’s python.exe directly. That avoids changing policy merely to install a package. Activation only adjusts the current shell; it is not required for the environment to work.
py -m venv .venv
.\.venv\Scripts\Activate.ps1
# Direct use without activation:
.\.venv\Scripts\python.exe -m pip --versionConfirm that Python and pip point to the same place
A prompt showing .venv is useful, but sys.executable is the clearer check. Its path should end inside your project’s .venv. python -m pip --version also reports where pip is installed. Run these checks in the terminal actually used to launch the application.
Then select the same interpreter in the editor. A common reason for ModuleNotFoundError is that a package was installed from one terminal, while the editor or server started a different Python. For notebooks, check the selected kernel as well.
python -c "import sys; print(sys.executable)"
python -m pip --versionInstall the project rather than random global packages
If requirements.txt exists, install it with the environment’s Python. For a new Django project, python -m pip install Django installs Django into this environment. For an existing project, use its dependency file so that you do not accidentally replace its intended versions.
A pinned requirements file helps reproduce package versions. pip freeze lists installed distributions, but does not record the operating system or Python version and can include temporary development tools. Review that file before treating it as the project’s dependency contract.
python -m pip install -r requirements.txt
python -m pip checkRecreate the environment on another machine
Exclude .venv from Git and deployment archives. Virtual environments can contain absolute interpreter paths and platform-specific packages, so copying the directory between Windows and Linux is unreliable. Transfer source and dependency files, then create a fresh environment at the destination.
For a server or scheduled task, call the environment’s interpreter by its full path. You do not need a shell to remain activated. This also makes the Python used by the service explicit when you inspect its startup command.
A short diagnosis when installation goes wrong
If pip is missing from the environment, try its Python with -m ensurepip --upgrade where the Python distribution supports ensurepip. If the environment itself was created with the wrong version, recreate it instead of attempting to convert it in place.
When a package is still unavailable, compare sys.executable, pip’s location and the editor’s interpreter. Check the installation error before repeating the command: a failed build or unsupported Python version is different from installing into the wrong environment. Use deactivate to leave an activated shell.
python -m pip show Django
deactivateThings to check
- Keep project source outside .venv.
- Use python -m pip with the intended interpreter.
- Exclude the environment directory from version control.
Where this applies
Requires a Python installation with venv support. Shell activation differs by platform.