How to Create a Python Virtual Environment on Ubuntu

Python virtual environments isolate project dependencies on Ubuntu, preventing package conflicts when multiple projects require different library versions. The virtualenv tool creates self-contained directories with independent Python interpreters and packages, letting you maintain clean separation between development environments without affecting the system-wide Python installation.

This guide covers installing virtualenv on Ubuntu, creating and activating virtual environments, and managing packages with pip. You’ll learn the complete workflow from initial setup to installing project-specific dependencies in isolated environments.

Pre-Installation Steps Before Creating Python Virtual Environment

Update Ubuntu

Before proceeding with the installation, refresh your Ubuntu package lists so you install the latest available packages. Open your terminal (press Ctrl+Alt+T, the Linux equivalent of launching Command Prompt or PowerShell in Windows) and run:

sudo apt update

This command refreshes your system’s package index. If you want to upgrade everything after reviewing the changes, run sudo apt upgrade. For automated security updates, consider configuring unattended upgrades on Ubuntu.

Install Python (Skip if Installed)

Python is the foundation for setting up a virtual environment. First, check if Python is already installed by running python3 --version. If it’s not installed, or you need a newer version, install Python with the following command:

python3 --version

sudo apt install python3

This installs the latest Python 3.x version in the Ubuntu repositories. If you need a specific Python version, refer to our guide on installing Python 3.8 on Ubuntu.

Install Virtual Environment (virtualenv)

To create isolated Python environments, you need the virtualenv package. This tool is essential for managing separate project environments, each with its own dependencies. Install virtualenv using APT (Ubuntu’s Advanced Packaging Tool, similar to Windows Update for desktop apps) by running:

First, verify whether virtualenv is already available on your system:

virtualenv --version

If the command prints a version number, you can skip the installation. Otherwise, add the package with APT:

sudo apt install python3-virtualenv

Upon completion, you have virtualenv installed, ready to create isolated Python environments for different projects.

Choose Your Virtual Environment Tool

Python offers two primary tools for creating virtual environments: the built-in venv module and the third-party virtualenv package. Understanding the differences helps you choose the right tool for your workflow.

The venv module ships with Python 3.3+ and requires no separate installation beyond the python3-venv package on Ubuntu. It provides lightweight virtual environments using symlinks and integrates directly with Python’s standard library. This makes it ideal for straightforward project isolation where you need basic dependency management without additional features.

In contrast, virtualenv offers advanced capabilities like faster environment creation, support for older Python versions, and more configuration options. It works across Python 2 and Python 3 (though Python 2 reached end-of-life in 2020), and provides features like environment cloning and customizable activation scripts. Choose virtualenv when you need these advanced features or manage legacy projects.

For most Ubuntu users working with modern Python 3 projects, venv delivers everything needed with zero installation overhead. This guide covers both approaches, starting with virtualenv for its broader feature set, then demonstrating venv as a streamlined alternative.

Create a Virtual Environment with Python

Create the Virtual Environment

Once you have Python and virtualenv installed, you can create a virtual environment. This environment is a self-contained directory that holds your project’s Python interpreter and any necessary packages. To create a virtual environment, use the following command:

virtualenv env

In this command, virtualenv is the tool you’re using, and env is the name of your virtual environment. You can replace env with any name you prefer for your project’s environment. To target a specific interpreter version you installed, point virtualenv at it directly:

virtualenv -p python3.12 .venv

This flexibility in naming and interpreter selection allows for easy identification of environments and keeps legacy or multi-version projects isolated.

The created directory contains the complete virtual environment structure:

env/
├── bin/          # Activation scripts and Python executables
├── include/      # C headers for compiling Python packages
├── lib/          # Python standard library and installed packages
└── pyvenv.cfg    # Configuration file with Python version info

This structure isolates your project’s Python interpreter, libraries, and scripts from the system installation.

Activate the Virtual Environment

Once your virtual environment is set up, the next step is to activate it. Activating the environment allows you to work within it, using its isolated Python interpreter and packages. To activate your virtual environment, use the following command:

source env/bin/activate

Here, source is a shell command that reads and executes commands from the file specified. In this case, env/bin/activate is the file that activates your environment. Remember to replace env with your virtual environment’s name if you named it differently.

Confirming Activation

Upon successful activation, you’ll notice a change in your terminal prompt. It will display the name of your virtual environment, confirming that it’s active. For instance, if your virtual environment is named env, your terminal prompt will look like this:

(env) joshua@ubuntu-linux:~$ 

The (env) prefix serves as your primary visual indicator that you’re working within an isolated environment. This change in the prompt indicates that you are now working inside the virtual environment. Consequently, any Python packages you install while the environment is active will be installed within this isolated environment, not affecting the global Python installation.

Deactivate the Virtual Environment

To exit the virtual environment and revert to your system’s default Python environment, use the deactivate command:

deactivate

This command ceases the virtual environment’s operation, returning your terminal to the system environment.

Alternative Method: Using Python’s Built-in venv Module

Python includes the venv module as a built-in tool for creating virtual environments without installing third-party packages. This method offers a lightweight alternative that works identically to virtualenv for most use cases.

Install python3-venv Package

Ubuntu systems require the python3-venv package to enable the venv module. Install it using:

Check whether the package is already installed before proceeding:

apt list --installed python3-venv

If the output shows [installed], you can jump to the creation steps. Otherwise, install the support package with:

sudo apt install python3-venv

This package provides the necessary components for creating virtual environments with Python’s standard library.

Create Virtual Environment with venv

Once installed, create a virtual environment using the python3 -m venv command followed by your desired environment name:

python3 -m venv myproject

This creates a directory named myproject containing the Python interpreter, pip, and supporting files. The -m flag tells Python to run the venv module as a script. To pin a specific Python version you installed, call that interpreter explicitly:

python3.12 -m venv .venv

To bootstrap with the latest pip, setuptools, and wheel in one step, add the --upgrade-deps flag:

python3 -m venv --upgrade-deps .venv

Use the interpreter that matches your project’s baseline so you avoid surprises when deploying.

Activate and Deactivate venv Environments

Activation works identically to virtualenv. Navigate to your project directory and run:

source myproject/bin/activate

Your prompt changes to show the environment name, indicating activation succeeded. To deactivate, simply use the same deactivate command as with virtualenv.

Verify Active Environment

When working with multiple environments, confirm which one is active using these verification commands:

echo $VIRTUAL_ENV

This displays the full path to your active virtual environment directory. If no environment is active, the output will be empty.

Additionally, check which Python interpreter you’re using:

which python3

Inside an active environment, this points to the environment’s Python binary instead of the system-wide installation.

To list all packages installed in your active virtual environment, use:

python -m pip list

This displays every package and its version currently installed in the environment, helping you verify the environment’s state and track dependencies.

Managing Python Packages in Virtual Environments

Check pip Availability

Virtual environments created with virtualenv or python3 -m venv include pip by default. After activating your environment, confirm pip is present:

python -m pip --version

If this fails, install pip system-wide so new environments can seed their own copy:

sudo apt install python3-pip

Update pip After Activation

Keep pip and its build helpers current inside each environment to pick up the latest fixes and smoother dependency builds:

python -m pip install --upgrade pip setuptools wheel

Install a Python Package

Install project dependencies from inside the active environment so nothing leaks into the system site packages. Replace <package_name> with the library you need:

python -m pip install <package_name>

For example, to add requests:

python -m pip install requests

Avoid using sudo pip on Ubuntu because it writes outside the virtual environment and can conflict with apt-managed packages. Keep installs inside an activated virtual environment so dependencies stay isolated from the system Python.

Remove a Python Package

Uninstall dependencies from the active environment the same way:

python -m pip uninstall <package_name>

For example, to remove requests:

python -m pip uninstall requests

Managing Dependencies with requirements.txt

When collaborating on projects or deploying applications, tracking installed packages ensures everyone works with identical dependencies. Python’s requirements.txt file provides a standard method for documenting and sharing your environment’s exact package versions.

To capture your current environment’s packages, run pip freeze while the environment is active:

python -m pip freeze > requirements.txt

This command lists all installed packages with their versions and writes them to requirements.txt. The file contents look like:

requests==2.31.0
certifi==2023.7.22
charset-normalizer==3.2.0

To replicate this environment on another system or in a fresh virtual environment, install from the requirements file:

python -m pip install -r requirements.txt

This installs every package listed with its specified version, ensuring consistency across development, testing, and production environments.

Practical Application in Virtual Environments

Run these pip commands only after activating a virtual environment to keep dependencies isolated, reproducible, and separate from your system Python packages.

Virtual Environment Best Practices

Following established conventions ensures your virtual environments remain maintainable and portable across development teams and deployment environments.

Naming Conventions

Use .venv or venv as your environment directory name. The dot prefix hides the directory in file listings on Linux, reducing clutter in project folders. Alternatively, env or project-specific names work when managing multiple environments in separate directories.

Version Control Exclusion

Never commit virtual environment directories to Git or other version control systems. These directories contain thousands of files specific to your system’s Python installation and take significant repository space. Instead, add your environment directory to .gitignore:

# .gitignore
venv/
.venv/
env/
ENV/

Commit your requirements.txt file instead, letting team members recreate the environment locally with python -m pip install -r requirements.txt.

Environment Recreation

Treat virtual environments as disposable. If an environment becomes corrupted or accumulates unnecessary packages, delete the directory and recreate it from your requirements.txt. This takes seconds and guarantees a clean state matching your documented dependencies.

Conclusion

Python virtual environments isolate project dependencies on Ubuntu, preventing package conflicts across projects. The virtualenv tool creates these isolated environments, while pip manages packages within them. Your Ubuntu system now supports multiple Python projects with independent dependency chains, each activated and managed through simple terminal commands.