Install Python and Set Up a venv Virtual Environment (Win, Mac, Linux)

This article is a localized edition of the Japanese original. Read the Japanese original

The basic flow when you start using Python is to install Python in the way that suits your OS, create a virtual environment for each project with python -m venv .venv, and install libraries inside it. Keeping virtual environments separate prevents library versions from clashing between projects and keeps you from breaking the Python that ships with your OS. This article covers installation on Windows, macOS, and Linux (Ubuntu), creating, activating, and deleting a venv, using a virtual environment's Python from a server cron job and the like, and how to fix common errors.

Which version to install

Python releases a new minor version (numbered like 3.13 or 3.14) around October each year, and each is supported for about five years. If you are starting something new, it is safest to choose a fairly recent version that still has a long support period left, and to check that the libraries you want to use support it. You can check the support status of each version in the official python.org documentation (the "Status of Python versions" page of the Python Developer's Guide) (as of October 2026).

Versions whose support has ended no longer receive security fixes. If you are taking over a script that runs on an old server, check the version you have first.

python3 --version

Installation by OS

Windows

The basic way is to get the installer from python.org. Recently, python.org has been promoting a new way to install called the "Python install manager," which can manage multiple versions, and the move away from the traditional installer is progressing. Which method is recommended changes over time, so follow the guidance on the download page.

If you use the traditional installer, check the option on the first screen that adds python.exe to PATH, and you will be able to start it with python from Command Prompt or PowerShell. After installing, check with the following commands.

python --version
py --list

py is the launcher for Windows, and you can start a specific version with it, as in py -3.13.

If the Microsoft Store opens when you type python: Windows has an "app execution alias" that points you to the Store when Python is not installed. If you use the python.org version, turn off the aliases for python.exe and python3.exe under "App execution aliases" in the Apps section of Windows Settings (the location and wording of the settings screen differ by Windows version).

macOS

macOS may have python3 installed along with the Xcode Command Line Tools, but you cannot choose the version, so it is common to install one separately for development.

• Use the macOS installer from python.org
• If you use Homebrew, install a specific version, as in brew install python@3.13

You can check which Python is being used with which python3. If several are installed, an unintended one may start.

Linux (Ubuntu and Debian family)

Ubuntu comes with Python from the start, but the OS's own tools also use this Python. Do not replace the OS's Python with a different version or delete it. It affects how the system works.

To use venv, you need an additional package.

sudo apt update
sudo apt install python3 python3-venv python3-pip

If you need a version different from the OS default, you can build one in the user's home directory with pyenv, or use uv's uv python install. Neither touches the OS's Python, so they are relatively safe to use on servers too.

Create a virtual environment (venv)

Create

Move to the project folder and run the following commands.

cd ~/projects/report-tool
python3 -m venv .venv

On Windows, use python -m venv .venv or py -3.13 -m venv .venv. .venv is the folder name of the virtual environment. A different name is fine, but using .venv means editors often find it automatically.

The Python version used at creation time is carried over to the virtual environment. If you want to create one with a different version, run -m venv with that version of Python.

Activate and deactivate

When you "activate" a virtual environment, the python and pip commands switch to the ones inside the virtual environment.

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Switch back (same for all)
deactivate

When activated, something like (.venv) appears at the start of the prompt. You can check that it really switched with the following command.

python -c "import sys; print(sys.prefix)"

If the path shown is the project's .venv, you are running inside the virtual environment.

If PowerShell says that running scripts is disabled: PowerShell's execution policy is blocking Activate.ps1. On a company PC, an administrator may set the policy, so check your company's rules before changing it. Even without activating, you can use the virtual environment's Python by running .venv\Scripts\python.exe directly.

Install libraries

If you use pip while the environment is activated, libraries are installed only inside the virtual environment.

python -m pip install --upgrade pip
python -m pip install requests

Writing python -m pip instead of pip calls the pip that belongs to the Python you are currently using, which prevents mix-ups. Details on using pip (specifying versions and managing requirements.txt) are covered in a separate article.

Rules for handling virtual environments

Do not include it in Git: The .venv folder can reach several hundred MB, and its contents depend on the OS and paths, so do not put it in the repository. Write .venv/ in .gitignore. With Python 3.13 and later, venv automatically places a .gitignore inside the virtual environment folder when it creates one, but writing it on the project side as well is more reliable. Instead, manage the list of installed libraries (such as requirements.txt) in the repository.

Do not move or copy it: The path of the place where it was created is written inside the virtual environment. If you move the whole folder somewhere else, it stops working, so if you want to move it, delete it and recreate it.

deactivate            # Deactivate if it is activated
rm -rf .venv          # On Windows, Remove-Item -Recurse .venv
python3 -m venv .venv
python -m pip install -r requirements.txt

Recreate it when you update Python: If you upgrade the original Python, it is also safer to recreate the virtual environment.

Use it with server cron and systemd

For scripts that run on a schedule on a server, you do not need to use activate. If you specify the full path to the python inside the virtual environment, that virtual environment's libraries are used.

# crontab example (runs every day at 3:00)
0 3 * * * /home/deploy/report-tool/.venv/bin/python /home/deploy/report-tool/main.py >> /home/deploy/report-tool/cron.log 2>&1

cron has a different environment from a login session, and activating with source may not work, so this way of writing it causes fewer problems. In a systemd service too, write the full path to the virtual environment's python in ExecStart in the same way.

Common errors and fixes

The virtual environment was not successfully created because ensurepip is not available: The python3-venv package is not installed on Debian/Ubuntu. Run sudo apt install python3-venv. A version-specific package (for example, python3.12-venv) may be needed, and the error message shows the name of the package to install.

error: externally-managed-environment: You are trying to pip install into the OS's Python without activating a virtual environment. Recent Ubuntu and Debian block this operation to protect the OS's Python. Create a virtual environment and install inside it.

python: command not found (Linux and macOS): In many environments the command is named python3. If you activate the virtual environment, python works inside it.

A library is not found even though the environment is activated (ModuleNotFoundError): Often the editor or IDE is using a different Python. In VS Code, use the command palette's option for selecting the Python interpreter and point it to the Python inside .venv.

Summary

• Choose a fairly recent supported version of Python, and do not replace the Python that comes with the OS
• On Windows, follow the guidance on python.org, and if the Store opens when you run python, check the app execution aliases
• On Ubuntu, you need python3-venv for venv
• Create one per project with python -m venv .venv, and install libraries with python -m pip
• Do not put .venv in Git, and recreate it if you move it or update Python
• With cron and systemd, specify the full path to .venv/bin/python without activating

• How to manage packages with Python's pip
• How to run a Python script on a schedule with cron

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)