Getting started

This tutorial will teach you the basics of virtualenv through hands-on practice. You’ll create your first virtual environment, install packages, and learn how to manage project dependencies.

Prerequisites

Before starting this tutorial, you need:

  • Python 3.9 or later installed on your system. If you use a version manager like pyenv, mise, or asdf, virtualenv will automatically discover the Python version they manage.

  • virtualenv installed (see Install virtualenv).

Create your first virtual environment

Let’s create a virtual environment called myproject:

$ virtualenv myproject
created virtual environment CPython3.13.2.final.0-64 in 200ms
  creator CPython3Posix(dest=/home/user/myproject, clear=False, no_vcs_ignore=False, venv_redirect=None, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, via=copy, app_data_dir=/home/user/.cache/virtualenv)
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator

This creates a new directory called myproject containing a complete, isolated Python environment with its own copy of Python, pip, and other tools.

pyvenv.cfg inside it records which Python the environment came from:

$ grep python-version myproject/pyvenv.cfg
python-version = 3.13

That key tells an editor or a type checker which language version your code targets.

The interpreter answers to several names, so a script expecting any of them keeps working inside the environment:

$ ls myproject/bin/python*
myproject/bin/python  myproject/bin/python3  myproject/bin/python3.13

When you create the environment inside a project folder, one with a pyproject.toml, virtualenv writes a .venv redirect file naming it:

$ cat .venv
myproject

Editors and type checkers read that file to find the environment, so they can offer the right interpreter before you activate anything. A second environment in the same folder leaves the redirect as it is; pass --venv-redirect to point it at the new one, or --no-venv-redirect to write nothing. The redirect is provisional and may change as PEP 832 evolves. Environment layout lists every interpreter name, and Generated files covers every file.

Activate the environment

To use your virtual environment, you can activate it. The activation command differs by platform:

$ source myproject/bin/activate

PS> .\myproject\Scripts\Activate.ps1

C:\> .\myproject\Scripts\activate.bat

After activation, your prompt changes to show the active environment:

(myproject) $

You can verify that Python is now running from inside the virtual environment:

(myproject) $ which python
/home/user/myproject/bin/python

(myproject) PS> where.exe python
C:\Users\user\myproject\Scripts\python.exe

(myproject) C:\> where.exe python
C:\Users\user\myproject\Scripts\python.exe

Install a package

With the environment activated, install a package using pip:

(myproject) $ pip install requests
Collecting requests
  Using cached requests-2.32.3-py3-none-any.whl (64 kB)
Installing collected packages: requests
Successfully installed requests-2.32.3

Verify that the package is installed only inside your virtual environment:

(myproject) $ python -c "import requests; print(requests.__file__)"
/home/user/myproject/lib/python3.13/site-packages/requests/__init__.py

The path shows that requests is installed in the virtual environment, not in your system Python.

Deactivate

When you’re done working in the virtual environment, deactivate it:

(myproject) $ deactivate
$

The prompt returns to normal, and Python commands now use your system Python again.

Use without activation

Activation is a convenience, not a requirement. You can run any executable from the virtual environment directly by using its full path:

$ myproject/bin/python -c "import sys; print(sys.prefix)"
/home/user/myproject

$ myproject/bin/pip install httpx

PS> .\myproject\Scripts\python.exe -c "import sys; print(sys.prefix)"
C:\Users\user\myproject

PS> .\myproject\Scripts\pip.exe install httpx

C:\> .\myproject\Scripts\python.exe -c "import sys; print(sys.prefix)"
C:\Users\user\myproject

C:\> .\myproject\Scripts\pip.exe install httpx

This is especially useful in scripts, CI pipelines, and automation where modifying the shell environment is unnecessary.

Set up a real project

Now let’s apply what you’ve learned to a real project workflow:

$ mkdir myapp && cd myapp
$ virtualenv venv
$ source venv/bin/activate  # or use the appropriate command for your platform
(venv) $ pip install flask requests
(venv) $ pip freeze > requirements.txt

The requirements.txt file now contains your project’s dependencies:

blinker==1.9.0
certifi==2025.1.31
charset-normalizer==3.4.1
click==8.1.8
flask==3.1.0
idna==3.10
itsdangerous==2.2.0
Jinja2==3.1.5
MarkupSafe==3.0.2
requests==2.32.3
urllib3==2.3.0
werkzeug==3.1.3

This file lets you recreate the exact environment later. Let’s test this:

(venv) $ deactivate
$ rm -rf venv
$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt

All packages are reinstalled exactly as before. Here’s the complete workflow:

        graph TD
    A[Create virtual environment] --> B[Activate]
    B --> C[Install packages]
    C --> D[Freeze to requirements.txt]
    D --> E[Deactivate & clean up]
    E --> F[Recreate virtual environment]
    F --> G[Install from requirements.txt]
    G --> H[Ready to work]

    style A fill:#2563eb,stroke:#1d4ed8,color:#fff
    style B fill:#6366f1,stroke:#4f46e5,color:#fff
    style C fill:#6366f1,stroke:#4f46e5,color:#fff
    style D fill:#6366f1,stroke:#4f46e5,color:#fff
    style E fill:#d97706,stroke:#b45309,color:#fff
    style F fill:#6366f1,stroke:#4f46e5,color:#fff
    style G fill:#6366f1,stroke:#4f46e5,color:#fff
    style H fill:#16a34a,stroke:#15803d,color:#fff

What you learned

In this tutorial, you learned how to:

  • Create a virtual environment with virtualenv.

  • Activate and deactivate virtual environments on different platforms.

  • Install packages in isolation from your system Python.

  • Save project dependencies with pip freeze.

  • Reproduce environments using requirements.txt.

  • Let editors find your environment through the .venv redirect file.

Next steps

Now that you understand the basics, explore these topics:

  • Use virtualenv for selecting specific Python versions, configuring defaults, and advanced usage patterns.

  • Explanation for understanding how virtualenv works under the hood and how it compares to venv.

  • Command line for all available command line options and flags.

  • Verify a virtualenv release to check that the virtualenv you downloaded came from its release workflow.

  • Generated files for every file virtualenv writes inside and beside an environment.