2026-04-1310 min read

Python Packaging User Guide: Creating and using virtual environments

Learn Python Packaging User Guide: Creating and using virtual environments step by step with clear examples and exercises.

Why This Matters

Learning to create and use virtual environments in Python is essential for managing dependencies and avoiding conflicts between different projects. Virtual environments ensure that each project has its own isolated environment, preventing potential conflicts between dependencies and making it easier to manage your project's requirements efficiently. In addition, using virtual environments can help you share your code with others by ensuring that they have the exact same dependencies as your project.

By creating a separate environment for each project, you can maintain consistency across different development machines, avoid package version conflicts, and simplify the process of installing, updating, and managing dependencies. This leads to more reliable and reproducible code, which is especially important when collaborating with others or deploying your projects to production environments.

Prerequisites

Basic understanding of Python programming: Familiarity with variables, functions, loops, and control structures is essential for working with virtual environments effectively.
Familiarity with the command line or terminal: Being comfortable navigating directories, running commands, and managing files using the command line is necessary to create and manage virtual environments.
A text editor or Integrated Development Environment (IDE): Choosing an IDE like Visual Studio Code, PyCharm, or Jupyter Notebook can help you write, run, and debug your Python code more efficiently.
Basic knowledge of the Python Package Index (PyPI) and pip: Understanding how to install packages using pip is crucial for working with virtual environments.

Core Concept

Creating a virtual environment

To create a new virtual environment, you can use the venv module that comes with Python. Here's how to do it:

python3 -m venv my_virtual_env

Replace my_virtual_env with the name you want for your virtual environment. This command creates a new directory called my_virtual_env in your current working directory and installs the necessary files to manage the virtual environment.

Activating a virtual environment

To activate the virtual environment, navigate to its directory using the command line and run:

source my_virtual_env/bin/activate

Once activated, your terminal prompt will change to show the name of the active virtual environment. Now, any Python packages you install or update will be installed within this isolated environment.

Installing packages

Within an active virtual environment, you can use pip, the Python package manager, to install packages. For example:

pip install requests

This command installs the requests library in your current virtual environment. You can also create a requirements.txt file listing all the dependencies required for your project and use it to install the necessary packages:

pip install -r requirements.txt

Deactivating a virtual environment

To deactivate a virtual environment, simply run:

deactivate

Managing virtual environments with tools like pipenv and poetry

While venv is a simple way to manage virtual environments, tools like pipenv and poetry offer additional features like automatic dependency management, lockfiles, simplified installation of development dependencies, and better integration with popular IDEs and version control systems. They can help manage larger projects more efficiently and make it easier for collaborators to set up and maintain the project's environment.

Pipenv

Pipenv is a tool that combines package management, virtual environment creation, and dependency management into a single command-line interface. To install pipenv, run:

pip install pipenv

Then, create a new project with pipenv by running:

pipenv init

This command creates a Pipfile and Pipfile.lock file in your project directory, along with a virtual environment. You can add dependencies to the Pipfile, and pipenv will handle creating and activating the virtual environment when you run your Python scripts.

Poetry

Poetry is another popular tool for managing Python projects and their dependencies. To install poetry, run:

curl -sSL https://install.python-poetry.org | python3 -

Then, create a new project with poetry by running:

poetry init

This command creates a pyproject.toml file in your project directory, along with a virtual environment. You can add dependencies to the pyproject.toml file, and poetry will handle creating and activating the virtual environment when you run your Python scripts.

Worked Example

Let's create a new project and set up a virtual environment for it using pipenv:

Create a new directory for your project:

mkdir my_project
cd my_project

Install pipenv:

pip install pipenv

Initialize the project with pipenv:

pipenv init

Create a requirements.txt file listing your project's dependencies:

echo "requests" > requirements.txt

Install the listed dependencies:

pipenv install

Activate the virtual environment:

pipenv shell

Verify that the requests package is installed:

pip list

You should see requests listed among the installed packages. To create a script that uses this package, you can create a new Python file called main.py and write some code that imports and uses the requests library.

Deactivate the virtual environment:

exit

Common Mistakes

Not activating the virtual environment before installing packages: If you forget to activate the virtual environment, packages will be installed globally instead of within the isolated environment. This can lead to conflicts between projects that use different versions of the same package. To avoid this mistake, always remember to activate your virtual environment before installing new packages.
Using global packages in your code: When writing code within a project that uses a virtual environment, make sure to import packages using their full path (e.g., venv/lib/python3.x/site-packages/requests). This ensures you're using the correct version of the package installed in your virtual environment.
Not deactivating the virtual environment after use: Leaving a virtual environment activated can cause confusion when working on other projects, as it may affect which packages are installed or used. Always remember to deactivate the virtual environment when you're done with it.
Installing the same package twice: If you have multiple virtual environments and install the same package in each one, it will create duplicate copies of that package. To avoid this mistake, consider using tools like pipenv or poetry for managing dependencies more efficiently.
Not creating a requirements.txt file: Failing to create or update the requirements.txt file can make it difficult for others to replicate your environment and run your code correctly. Always remember to create and maintain an up-to-date requirements.txt file for your project.
Not using a version manager like pipenv or poetry: While venv is a simple way to manage virtual environments, tools like pipenv and poetry offer additional features like automatic dependency management, lockfiles, simplified installation of development dependencies, and better integration with popular IDEs and version control systems. Consider using one of these tools for larger projects or when working with multiple collaborators.
Not updating the requirements.txt file when adding new dependencies: Make sure to update your requirements.txt file whenever you add a new dependency to your project, so that others can easily replicate your environment and run your code correctly.
Ignoring warnings or errors during package installation: When installing packages, it's important to pay attention to any warnings or errors that appear in the console. These messages may indicate potential issues with the installed packages or dependencies, which could affect the performance or stability of your project. If you encounter any warnings or errors, consider researching the issue and finding a solution before continuing with your project.
Not using a lockfile: Using a lockfile can help ensure that your project always has the same dependencies, even if other developers make changes to their local environments or install new packages. This can prevent conflicts and improve reproducibility when working with multiple collaborators. Make sure to use a lockfile (e.g., Pipfile.lock for pipenv or pyproject.toml for poetry) whenever possible.
Not testing your project's dependencies: It's important to test your project's dependencies to ensure that they are compatible with your code and don't cause any unexpected issues. You can do this by running tests, checking the package documentation, and verifying that the packages work as expected in your project.

Practice Questions

How can you create a new virtual environment for a project called my_awesome_project?

Using the command line, navigate to your project directory and run: python3 -m venv my_awesome_project_env.

What command do you run to activate the virtual environment?

Run: source my_awesome_project_env/bin/activate (on Linux or macOS) or my_awesome_project_env\Scripts\activate (on Windows).

Suppose you have a project that requires two versions of the numpy library (one for development and one for production). How would you manage this using virtual environments?

Create two separate virtual environments, one for development and another for production, and install the required versions of numpy in each environment. Use pip freeze to create a requirements.txt file for each environment, listing all the dependencies required for their respective roles.

You've accidentally installed a package globally instead of within your current virtual environment. What can you do to fix this issue?

Deactivate the virtual environment and uninstall the incorrectly installed package using pip uninstall . Then, reactivate the virtual environment and install the correct version of the package.

Explain why it's important to deactivate a virtual environment after use.

Deactivating a virtual environment ensures that your system's Python path is not modified, allowing you to work on other projects with their own dependencies without encountering conflicts or unexpected behavior. It also helps prevent confusion when working on multiple projects that use different versions of the same packages.

How can you ensure that your project has all the necessary dependencies installed?

Create a requirements.txt file listing all the dependencies required for your project, and use it to install the necessary packages using: pip install -r requirements.txt. Make sure to update the requirements.txt file whenever you add new dependencies to your project.

What are some advantages of using tools like pipenv or poetry over the built-in venv module?

Tools like pipenv and poetry offer additional features like automatic dependency management, lockfiles, simplified installation of development dependencies, and better integration with popular IDEs and version control systems. They can help manage larger projects more efficiently and make it easier for collaborators to set up and maintain the project's environment.

How can you use pipenv or poetry to install development dependencies that are not listed in the requirements.txt file?

With pipenv, you can add development dependencies to the Pipfile.dev file instead of the main Pipfile. With poetry, you can use the --dev flag when installing packages: poetry install --dev.

How can you upgrade all installed packages in a virtual environment using pipenv?

To upgrade all installed packages in a virtual environment using pipenv, run: pipenv update --upgrade.

What is the purpose of a lockfile in Python packaging, and how does it help prevent issues with dependency management?

A lockfile records the exact versions of all installed packages in a project's virtual environment. Using a lockfile can help ensure that your project always has the same dependencies, even if other developers make changes to their local environments or install new packages. This can prevent conflicts and improve reproducibility when working with multiple collaborators.

FAQ

Why should I use virtual environments when working on multiple projects? Using virtual environments helps manage dependencies and prevents potential conflicts between different projects by keeping each project's requirements isolated. It also makes it easier to share your code with others by ensuring that they have the exact same dependencies as your project.
Can I have multiple active virtual environments at the same time? Yes, you can activate multiple virtual environments, but remember that each activated environment will modify your system's Python path. It's recommended to deactivate unused virtual environments when not in use.
How do I install a package globally if needed? To install a package globally, simply run pip install without activating a virtual environment. However, it's best to avoid this practice whenever possible, as it can lead to conflicts between projects that use different versions of the same package.
What happens if I forget to activate a virtual environment before running my Python script? If you forget to activate the virtual environment and run your script, it will use the global installation of Python packages instead of the isolated environment's packages. This can lead to unexpected results or errors. To avoid this mistake, always