Python Version Management Guide: pyenv, venv, Anaconda

1. Introduction

Python is a popular programming language used by a wide range of users, from beginners to professionals. However, because Python versions are updated frequently, many people find it challenging to maintain development environments and manage versions across different projects.

This article explains why Python version management is important and how to manage versions in detail. It also covers how to choose version management tools and provides concrete usage examples, so if you want to use Python more efficiently, please refer to it.

1-1. Why Python version management is important

To understand why Python version management is important, consider the following scenarios.

1-1-1. Different projects may require different Python versions

In corporate system development and individual programming projects, certain Python versions may be required due to the libraries or frameworks used. For example:

• Django 2.2 supports Python 3.5 to 3.8
• TensorFlow 1.x supports Python 2.7 or 3.5
• TensorFlow 2.x requires Python 3.6 or higher

Because different tools recommend different Python versions, failing to manage your environment properly can cause libraries to stop working.

1-1-2. Directly changing the system-installed Python can cause problems

Windows, macOS, and Linux may have Python installed as part of the system. Especially on Linux, some OS functions depend on Python, so changing the system Python version can cause unexpected errors.

If you overwrite the system Python by installing a different version without using a version manager, it may affect the OS’s behavior, so proper management is necessary.

1-1-3. Standardizing development environments makes team development smoother

In team development, it’s desirable for all members to work in the same environment. If a project’s Python version differs, behavior can vary by developer and lead to bugs.

Using version management tools allows everyone to use a unified environment, improving development efficiency.

1-2. How to manage Python versions

There are several ways to manage Python versions. The main tools include the following.

1-2-1. pyenv

The most widely used Python version management tool is pyenv. It allows you to easily switch between different Python versions and manage multiple versions without affecting the system Python.

1-2-2. venv

A virtual environment tool provided as part of the Python standard library that lets you create isolated environments per project. It’s slightly different from version management, but it’s useful when creating environments that depend on a specific Python version.

1-2-3. Anaconda

A tool for managing Python environments for data science and machine learning that uses the package management system called “conda” to manage Python versions.

1-2-4. asdf

A tool that can manage versions for multiple programming languages, not just Python, such as Node.js and Ruby. Because you can switch Python versions per project, it’s easier to maintain consistency in development environments.

1-3. Summary

Python version management is an important factor that greatly affects development efficiency and system stability. Especially for developers who work on multiple projects at once or users who want to try different Python versions, using the right management tool is essential.

The next section covers how to check your Python version in detail. By knowing which Python versions are installed in your environment, you’ll be prepared to manage versions smoothly.

2. How to check the Python version

Before managing Python versions, it’s important to understand how to check the Python version you’re currently using. If you don’t know the correct version, your code may run in an unexpected environment and cause problems.

This section explains how to check the Python version on Windows, macOS, and Linux.

2-1. How to check the Python version on Windows

On Windows, you can check the Python version using Command Prompt (cmd) or PowerShell.

2-1-1. How to check using Command Prompt

1. Press the [Win] key + [R] key, type ‘cmd’, and open Command Prompt.
2. Enter the following command and press Enter.

   python --version

or

   python -V

3. The current Python version will be displayed on the screen.

   Python 3.10.4

2-1-2. How to check using PowerShell

The basic steps are the same when using PowerShell.

1. Open the Start menu, search for ‘PowerShell’, and launch PowerShell.
2. Enter the following command and press Enter.

   python --version

3. The Python version will be displayed on the screen.

Notes:

• Depending on where Python is installed, you may need to use python3 instead of python.
• If the command is not recognized, check that your environment variables are configured correctly.

2-2. How to check the Python version on macOS

On macOS, Python is often installed by default, so you can use the Terminal to check the version.

2-2-1. How to check using Terminal

1. Press [Command] + [Space], type ‘Terminal’, and open Terminal.
2. Enter the following command.

   python3 --version

or

   python3 -V

3. The result will be displayed.

   Python 3.9.7

2-2-2. Note the difference between Python 2 and Python 3

On macOS, the python command may be linked to Python 2.x. When using Python 3.x, it is common to use the python3 command.

python --version  # May display Python 2.x
python3 --version  # Displays the Python 3.x version

Notes:

• On recent versions of macOS (Big Sur and later), Python 2.x is deprecated and Python 3.x is commonly used by default.

2-3. How to check the Python version on Linux

On Linux, many distributions (Ubuntu, Debian, CentOS, Fedora, etc.) come with Python preinstalled. Use the Terminal to check the version.

2-3-1. How to check using Terminal

1. Open a terminal and run the following command.

   python3 --version

or

   python3 -V

2. The output will look like this.

   Python 3.8.10

2-3-2. How to check if Python 2 is installed

On some older systems, Python 2.x may still be present. You can check with the following command.

python --version

If this command shows Python 2.x.x, Python 2.x may be the default.

2-3-3. If Python is not installed

If running python3 --version results in an error such as ‘Command ‘python3′ not found’, Python may not be installed. In that case, you can install it using the following commands.

Ubuntu/Debian:

sudo apt update
sudo apt install python3

CentOS/RHEL:

sudo yum install python3

Fedora:

sudo dnf install python3

2-4. Summary

The method for checking the Python version varies slightly across Windows, macOS, and Linux, but generally you use the python --version or python3 --version commands.

• Windows → In Command Prompt (cmd) or PowerShell, use python --version
• macOS → In Terminal, use python3 --version
• Linux → In Terminal, use python3 --version; if Python 2 is present, also check python --version

To manage versions properly, it’s important to first accurately understand your current environment. The next section will explain how to choose Python version management tools and detail their features.

Ad

3. How to Choose a Python Version Management Tool

Using a dedicated tool is the most efficient way to properly manage Python versions. However, because there are various version management tools available, you may be unsure which one to choose.

This section introduces representative tools used for Python version management and explains their features and suitable use cases.

3-1. Types of Python Version Management Tools

Python version management tools include the following types.

Each tool has its pros and cons, so it’s important to choose the right one for your needs.

3-2. pyenv (Best for Python version management)

3-2-1. What is pyenv?

pyenv is a tool that makes it easy to switch Python versions.
It is useful when you need to use different Python versions for specific projects or development environments.

3-2-2. Benefits of pyenv

• Allows multiple Python versions to coexist
• Does not affect the system Python
• Switch versions with a single command
• Available on Windows, macOS, and Linux

3-2-3. Recommended for

• Want to use different Python versions per project
• Want to switch versions easily
• Don’t want to change the global Python version

3-3. venv (When using virtual environments)

3-3-1. What is venv?

venv is Python’s standard tool for creating virtual environments. Its purpose is not to manage the Python version itself, but to create isolated environments per project.

3-3-2. Benefits of venv

• Included with Python by default; no additional installation required
• Allows managing different libraries per virtual environment
• Can isolate a project’s dependencies

3-3-3. Recommended for

• Want to separate library environments per project
• Want to manage environments without installing new tools
• Want to use virtual environments rather than manage Python versions

3-4. Anaconda (For data science and machine learning)

3-4-1. What is Anaconda?

Anaconda is a Python distribution optimized for data science and machine learning development. It uses the package management tool conda to manage Python versions and libraries.

3-4-2. Benefits of Anaconda

• Includes data science libraries (numpy, pandas, scikit-learn, etc.)
• Works well with Jupyter Notebook
• Easy package management (using the conda command)

3-4-3. Recommended for

• Doing machine learning or data analysis
• Frequently uses Jupyter Notebook
• Want to set up Python environments easily

3-5. asdf (Multi-language version manager)

3-5-1. What is asdf?

asdf is a tool for centrally managing versions of multiple programming languages, not just Python, such as Node.js, Ruby, and Go.

3-5-2. Benefits of asdf

• Can manage languages other than Python in one place
• Can set different versions per project
• Can switch Python without affecting the global environment

3-5-3. Recommended for

• Use programming languages other than Python
• Want to flexibly switch versions per project
• Want to efficiently manage multiple development environments

3-6. Which tool should you choose?

Choose based on the following criteria to find the version management tool that best fits you.

3-7. Summary

Python version management tools have different characteristics. Which tool you should choose depends on what you will use Python for.

• General-purpose version management → pyenv
• Use virtual environments → venv
• Data science and machine learning → Anaconda
• Manage languages beyond Python → asdf

The next section will explain “Using Virtual Environments” in detail. It will introduce how using virtual environments lets you properly manage project-specific dependencies and maintain environment consistency.

4. Using Virtual Environments

Python’s version management requires the use of a virtual environment. By using virtual environments, you can build isolated environments per project and allow different libraries and Python versions to coexist.

This section explains the basic concepts of virtual environments and details how to use the main tools (venv, Poetry).

4-1. What is a virtual environment?

A virtual environment is a mechanism to isolate a Python runtime environment on a per-project basis. Normally, Python packages (libraries) are installed system-wide, but by using virtual environments you can manage different packages for each project.

4-1-1. Benefits of using virtual environments

• Prevents library conflicts between different projects
• For example, if Project A needs Django 3.2 and Project B needs Django 4.0, virtual environments allow them to coexist.
• Develop without polluting the system Python environment
• You can maintain a clean environment without affecting the system Python.
• Makes it easier to standardize environments in team development
• By using virtual environments and sharing requirements.txt or pyproject.toml, all team members can build the same environment.

4-2. Creating virtual environments with venv

Python includes the venv tool in the standard library for creating virtual environments. No additional installation is required, and you can start using it right away.

4-2-1. How to create a virtual environment

1. Create a directory for the project

   mkdir my_project
   cd my_project

2. Create the virtual environment

   python3 -m venv venv

Here, venv is the folder name for the virtual environment. You can choose any name.

4-2-2. Activating the virtual environment

Activating the virtual environment lets you use the Python and libraries specific to that environment.

On Windows:

venv/Scripts/activate

On macOS/Linux:

source venv/bin/activate

When activated, the prompt will show (venv).

(venv) user@hostname:~/my_project$

4-2-3. Deactivating the virtual environment

To deactivate the virtual environment, run the following command.

deactivate

4-2-4. Removing a virtual environment

If you no longer need a virtual environment, you can simply delete the folder.

macOS/Linux:

rm -rf venv

Windows:

rd /s /q venv

4-3. Managing virtual environments and dependencies with Poetry

In addition to the standard venv library, Poetry is also popular as a tool for more advanced package management.

4-3-1. What is Poetry?

Poetry is a tool that handles dependency management and virtual environment creation for Python projects. It offers more flexible management than venv and is well suited for modern Python development.

4-3-2. Installing Poetry

To install Poetry, run the following command.

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

After installation, you can verify with the following command.

poetry --version

4-3-3. Creating a virtual environment with Poetry

The steps to create a new project with Poetry and set up a virtual environment are as follows.

1. Create the project folder

   mkdir poetry_project
   cd poetry_project

2. Initialize the project with Poetry

   poetry init

• Enter project information interactively.
• A configuration file named pyproject.toml will be created.

1. Create the virtual environment

   poetry install

This will automatically create a virtual environment and install the required packages.

4. Activate the virtual environment

   poetry shell

5. Add and manage packages

   poetry add requests
   poetry add numpy@latest

6. Deactivate the virtual environment

   exit

4-4. Comparing venv and Poetry

Conclusion:

• If you want simple virtual environments → venv
• If you want to automate dependency management → Poetry

4-5. Summary

Using virtual environments makes Python package management efficient. Especially when handling different libraries per project or when you don’t want to pollute the system Python environment, using venv or Poetry is best.

• venv → Simple creation of virtual environments (Python standard)
• Poetry → Advanced virtual environment tool including dependency management

Next, we will cover best practices for version control and dependency management. Learn how to operate your Python development environment more efficiently.

Ad

5. Best Practices for Version and Dependency Management

Python version management and the use of virtual environments understood, here are best practices useful in real development environments. By applying appropriate management methods, you can prevent environment chaos and run Python projects efficiently.

5-1. Create a virtual environment per project

To manage Python versions properly, the basic rule is to create a virtual environment for each project.
Using the system Python as-is makes it easy for library conflicts and environment contamination to occur.

5-1-1. Recommended virtual environment management practices

1. Create a virtual environment for each project

   python3 -m venv venv

2. Activate the virtual environment

   source venv/bin/activate  # macOS/Linux
   venvScriptsctivate  # Windows

3. Install libraries

   pip install requests pandas

✅ Key points:

• Creating virtual environments prevents interference with libraries from other projects.
• It makes it easier to reproduce a consistent environment in team development.

5-2. Clarifying and managing dependencies

When sharing a project or rebuilding the environment in the future, it’s important to explicitly manage dependencies (the list of installed libraries).

5-2-1. Use requirements.txt

In Python, you can use the pip freeze command to save the list of currently installed libraries to requirements.txt.

1. Record the libraries in the current environment

   pip freeze > requirements.txt

2. Reinstall the same libraries in another environment

   pip install -r requirements.txt

✅ Benefits:

• Easily share the same environment with team members.
• Quickly reproduce a consistent library setup in a new environment.

5-2-2. Use pyproject.toml (when using Poetry)

If you use Poetry, it is recommended to list dependencies in pyproject.toml.

1. Add packages

   poetry add numpy pandas

2. Check the dependency files

   pyproject.toml
   poetry.lock

✅ Benefits:

• You can manage dependencies more concisely than with pip freeze.
• Easier to pin versions, improving environment reproducibility.

5-3. Manage development and production environments separately

Development and production environments may use different library versions and settings. Therefore, it’s best practice to clearly separate libraries used only for development from those required in production.

5-3-1. Prepare a requirements-dev.txt

Separating libraries needed only in the development environment (e.g., testing and formatter tools like pytest and black) keeps the production environment simple.

Example:

pip freeze > requirements-dev.txt

In production, use only the basic requirements.txt, and in development combine it with requirements-dev.txt for easier management.

5-4. Standardizing environments in team development

In team development, it’s important to standardize each member’s environment.
Here are points to properly manage versions so the project proceeds smoothly.

5-4-1. Standardize the Python version

• Use pyenv to ensure the team uses a unified Python version.
• Create a .python-version file in the project root to pin the Python version.

Example:

echo "3.10.4" > .python-version

5-4-2. Use .venv

When the team uses venv, creating the virtual environment in a hidden folder named .venv rather than a venv directory makes Git management easier.

Example:

python3 -m venv .venv

Then add .venv/ to .gitignore so the virtual environment folder is not included in the repository—this is best practice.

5-5. Common issues and solutions

5-5-1. Python installed with pyenv is not recognized

Solution: Run pyenv init and apply it to your shell.

pyenv init

Also, ensure the PATH environment variable is set properly.

5-5-2. venv virtual environment does not activate

Solution: On Windows, you may need to change PowerShell’s execution policy.

Set-ExecutionPolicy Unrestricted -Scope Process

5-5-3. Can’t import after pip install

Solution: Verify the virtual environment is activated.

which python
which pip

If the output paths are not pointing to the virtual environment, activate it with source venv/bin/activate.

5-6. Summary

By properly managing Python versions and dependencies, you can improve development efficiency and minimize environment issues.

✅ Key best practices

1. Create a virtual environment for each project
2. Manage dependencies with requirements.txt or pyproject.toml
3. Manage development and production environments separately
4. In team development, standardize the Python version to eliminate environment differences

6. FAQ (Frequently Asked Questions)

Managing Python versions and using virtual environments is an area that often raises questions for both newcomers and experienced users. This section highlights common questions and provides concrete answers.

6-1. Can I use multiple Python versions at the same time?

Yes, you can.
pyenv or asdf allow different Python versions to coexist on your system and let you use the appropriate version per project.

Solution: Using pyenv

1. Install different Python versions

   pyenv install 3.9.7
   pyenv install 3.10.4

2. Set the version globally or locally (per-project)

   pyenv global 3.10.4  # Set the default Python for the whole system
   pyenv local 3.9.7  # Use Python 3.9.7 in a specific project folder

✅ Tip: Using pyenv lets you manage multiple versions without changing the system Python.

6-2. How do I delete a virtual environment?

You can simply delete the directory for the virtual environment.

If using venv

rm -rf venv  # macOS/Linux
rd /s /q venv  # Windows

Removing a Poetry virtual environment

poetry env remove python

✅ Tip: Even if you delete a virtual environment, it’s easy to recreate if you have requirements.txt or pyproject.toml.

6-3. How do I use a different Python version for a specific project?

Using pyenv or venv is the common approach.

With pyenv

1. Specify the Python version inside the project folder

   pyenv local 3.8.10

2. Verify

   python --version

   Python 3.8.10

With venv

1. Create virtual environments with different Python versions for each project

   python3.8 -m venv venv38
   python3.10 -m venv venv310

2. Activate the environment you want to use

   source venv38/bin/activate  # Python 3.8 environment

✅ Tip: pyenv is ideal for switching versions, while venv is suitable for per-project environment management.

6-4. How to choose a version management tool?

✅ Tip: Choosing the right tool for your purpose makes environment management easier.

6-5. Changes from pyenv not reflected when running python --version

This issue may be due to your shell not being configured properly.

Solution

1. Run pyenv initialization command

   pyenv init

2. Add the following lines to .bashrc or .zshrc (you can also use ~/.bash_profile)

   export PATH="$HOME/.pyenv/bin:$PATH"
   eval "$(pyenv init --path)"
   eval "$(pyenv virtualenv-init -)"

3. Apply the changes

   source ~/.bashrc  # or source ~/.zshrc

✅ Tip: Make sure pyenv is properly applied to your shell configuration.

6-6. Which should I use: venv or Poetry?

Conclusion:

• If you need a simple virtual environment, use venv
• If you want automatic dependency management, use Poetry

✅ Tip: Poetry has a bit of a learning curve, but it’s useful in the long run.

6-7. How do I pin libraries installed with pip install to a project?

Use pip freeze to create a requirements.txt.

pip freeze > requirements.txt

Then, to install in another environment, use the following command.

pip install -r requirements.txt

✅ Tip: Using pip freeze helps ensure environment reproducibility.

6-8. Summary

This section answered common questions about Python version management and virtual environments.

✅ Key points

• If you need to manage multiple Python versions, use pyenv
• For per-project virtual environments, use venv or Poetry
• To pin dependencies, use requirements.txt or pyproject.toml
• On Windows, use pyenv-win and check your environment variable settings

This should deepen your understanding of Python version management and help you set up development environments more smoothly.

Ad