Python venv Cheatsheet

some usefull venv commands

Page content

Venv is a virtual environment management commandline tool. A much more simple one, comparing to Anaconda. Here are some usefull venv commands.

A python is trying to open a wooden box.

Python venv Cheat Sheet

Create a Virtual Environment

  • Standard command (Python 3.3+):

    python -m venv venv

    This creates a virtual environment named venv in your current directory.

  • With a specific Python version (if installed):

    python3.10 -m venv venv

    or using virtualenv:

    virtualenv -p /usr/local/bin/python3.10 venv

    (Requires virtualenv package).

Activate the Virtual Environment

  • On Windows: 
    .\venv\Scripts\activate
  • On macOS/Linux: 
    source venv/bin/activate
    The shell prompt should now show the environment name.

Deactivate the Virtual Environment

  • All platforms: 
    deactivate
    This returns you to your system Python.

Installing Packages

  • With pip: 
    pip install
    Example: 
    pip install numpy pandas
  • Upgrade pip (recommended): 
    python -m pip install --upgrade pip

Freeze and Export Requirements

  • Save current environment packages: 
    pip freeze > requirements.txt
  • Install from requirements file: 
    pip install -r requirements.txt
    Ensure your virtual environment is activated before running these commands.

Remove a Virtual Environment

deactivate
rm -rf <env path>

Common Pitfalls When Managing Python Virtual Environments

Forgetting to Activate the Virtual Environment

  • A frequent mistake is running commands without activating the intended virtual environment, leading to package installations in the global environment or the wrong venv. This can cause dependency conflicts and unpredictable behavior.

Not Pinning Package Versions

  • Using loose version specifiers (like >= instead of ==) in requirements.txt undermines reproducibility. Exact version pinning ensures that everyone working on the project uses the same package versions, preventing unexpected issues during deployment or collaboration.

Mixing Global and Virtual Environments

  • Accidentally installing packages globally or mixing global and virtual environments can create conflicts, especially if different projects require incompatible package versions. Always ensure you are operating within the correct environment.

Committing Virtual Environments to Version Control

  • Including the virtual environment directory (e.g., venv/) in version control bloats repositories and is unnecessary. Always add venv directories to .gitignore to keep your repository clean.

Neglecting to Separate Development and Production Dependencies

  • Failing to distinguish between development and production dependencies can result in bloated or insecure deployments. Use separate requirements files or configuration sections for each.

Lack of Documentation and Automation

  • Not documenting environment setup steps or failing to automate the process (with scripts or Makefiles) makes onboarding new contributors and reproducing environments more difficult.

Not Regularly Cleaning Up Old Environments

  • Over time, unused virtual environments can accumulate, wasting disk space and causing confusion. Regularly remove obsolete venvs to maintain a tidy workspace.

Ignoring System Python and Package Manager Boundaries

  • Modifying the system Python or mixing system package managers with pip can break system tools and introduce hard-to-diagnose issues. Always use venvs for project dependencies and avoid interfering with system-managed packages.

Summary Table

Pitfall Impact
Forgetting to activate venv Installs packages in wrong environment
Not pinning package versions Unpredictable builds, hard-to-reproduce bugs
Mixing global and virtual environments Dependency/version conflicts
Committing venv directories to version control Bloated, messy repositories
Not separating dev and prod dependencies Bloated/insecure production environments
Lack of documentation/automation Hard onboarding, inconsistent setups
Not cleaning up old environments Disk space waste, confusion
Modifying system Python or packages System instability, broken tools

Following best practices-such as always activating your venv, pinning dependencies, separating environments, and maintaining clear documentation-can help you avoid these common pitfalls.

Key Differences Between Conda and Virtual Environments for Reproducibility

Feature Conda Environments Python Virtual Environments (venv/virtualenv)
Scope of Management Manages Python packages and non-Python dependencies (e.g., system libraries, compilers) Manages only Python packages via pip
Python Version Control Can specify and install any Python version per environment Uses the system-installed Python version
Cross-Platform Consistency More consistent across different OS (Windows, macOS, Linux) due to managing all dependencies Relies on system libraries, which may differ by OS
Package Sources Uses Conda repositories (precompiled binaries, scientific stack) Uses PyPI (pip) for Python packages
Reproducibility Higher for complex, scientific, or mixed-language projects; can export full environment (conda env export) Good for pure-Python projects; may lack reproducibility if system dependencies are involved
Non-Python Dependencies Can install and manage (e.g., OpenBLAS, libpng) Cannot manage; must be installed separately
Environment Export/Import conda env export / conda env create for full reproducibility pip freeze > requirements.txt / pip install -r requirements.txt (Python packages only)
Performance Faster and more reliable for large scientific packages (e.g., numpy, pandas) May require compiling from source, especially on Windows
Complexity Slightly higher setup and management overhead Lightweight, simpler for basic Python projects

Summary of Key Points

  • Conda environments are ideal for reproducibility in projects requiring both Python and non-Python dependencies, or when exact replication across platforms is critical. Conda manages the entire stack-including Python itself, libraries, and even compilers-making it easier to share and reproduce complex environments, especially in data science and research contexts.

  • Python virtual environments (venv/virtualenv) are lightweight and excellent for isolating Python dependencies in pure-Python projects. However, they do not manage system-level or non-Python dependencies, so reproducibility may be compromised if your project relies on external libraries or specific system configurations.

  • Exporting and sharing environments: Conda allows you to export a full environment specification (conda env export), including all dependencies and their versions, which can be recreated exactly elsewhere. With virtual environments, pip freeze only captures Python packages, not system dependencies or the Python interpreter version.

  • Conclusion
    Use Conda for maximum reproducibility in scientific, cross-platform, or complex projects. Use Python virtual environments for lightweight, pure-Python projects where system dependencies are not a concern.