Python Version Management Guide: pyenv, venv, Anaconda

1 1. Introduction
2 2. How to check the Python version
3 3. How to Choose a Python Version Management Tool
4 4. Using Virtual Environments
5 5. Best Practices for Version and Dependency Management
6 6. FAQ (Frequently Asked Questions)

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

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

   python --version

   python -V

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.

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

   python --version

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

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

   python3 --version

   python3 -V

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

Open a terminal and run the following command.

   python3 --version

   python3 -V

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.

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.

Tool	Main Use / Features	Supported OS	Ease of Use
pyenv	Easily switch between different Python versions	Windows, macOS, Linux	◎
venv	Python’s built-in virtual environment feature. Allows creating per-project environments	All OSes	○
Anaconda（conda）	Environment management for data science and machine learning	Windows, macOS, Linux	○
asdf	Can manage versions of multiple programming languages	Windows, macOS, Linux	△

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.

Purpose / Use	Best Tool
Want to easily switch between different Python versions	pyenv
Want to use virtual environments	venv
Doing machine learning or data analysis	Anaconda
Want to manage languages other than Python in one place	asdf

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

Create a directory for the project

   mkdir my_project
   cd my_project

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:

venvScriptsctivate

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.

Create the project folder

   mkdir poetry_project
   cd poetry_project

Initialize the project with Poetry

   poetry init

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

Create the virtual environment

   poetry install

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

Activate the virtual environment

   poetry shell

Add and manage packages

   poetry add requests
   poetry add numpy@latest

Deactivate the virtual environment

   exit

4-4. Comparing `venv` and `Poetry`

Feature	venv	Poetry
Python standard tool	✅	❌ (requires additional installation)
Creates virtual environments	✅	✅
Dependency management	❌ (managed manually)	✅ (automatic management)
Package management	`pip` is used	Easily managed with the `poetry add` command
Beginner-friendly	✅	△ (some learning curve)

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.

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

Create a virtual environment for each project

   python3 -m venv venv

Activate the virtual environment

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

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.

Record the libraries in the current environment

   pip freeze > requirements.txt

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.

Add packages

   poetry add numpy pandas

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

Create a virtual environment for each project
Manage dependencies with requirements.txt or pyproject.toml
Manage development and production environments separately
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

Install different Python versions

   pyenv install 3.9.7
   pyenv install 3.10.4

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

Specify the Python version inside the project folder

   pyenv local 3.8.10

Verify

   python --version

   Python 3.8.10

With venv

Create virtual environments with different Python versions for each project

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

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?

Criteria	Recommended tool
Need to manage multiple Python versions	`pyenv`
Want to create simple virtual environments	`venv`
Want to set up an environment for data science/machine learning	`Anaconda`
Want to manage versions of languages other than Python	`asdf`

✅ 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

Run pyenv initialization command

   pyenv init

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 -)"

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`?

Item	venv	Poetry
Python standard tool	✅	❌ (requires separate installation)
Creating virtual environments	✅	✅
Dependency management	❌ (manual management)	✅ (automatic management)
Beginner friendly	✅	△ (some learning curve)

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.

1. Introduction

1-1. Why Python version management is important

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

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

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

1-2. How to manage Python versions

1-2-1. pyenv

1-2-2. venv

1-2-3. Anaconda

1-2-4. asdf

1-3. Summary

2. How to check the Python version

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

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

2-1-2. How to check using PowerShell

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

2-2-1. How to check using Terminal

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

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

2-3-1. How to check using Terminal

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

2-3-3. If Python is not installed

2-4. Summary

3. How to Choose a Python Version Management Tool

3-1. Types of Python Version Management Tools

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

3-2-1. What is pyenv?

3-2-2. Benefits of pyenv

3-2-3. Recommended for

3-3. venv (When using virtual environments)

3-3-1. What is venv?

3-3-2. Benefits of venv

3-3-3. Recommended for

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

3-4-1. What is Anaconda?

3-4-2. Benefits of Anaconda

3-4-3. Recommended for

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

3-5-1. What is asdf?

3-5-2. Benefits of asdf

3-5-3. Recommended for

3-6. Which tool should you choose?

3-7. Summary

4. Using Virtual Environments

4-1. What is a virtual environment?

4-1-1. Benefits of using virtual environments

4-2. Creating virtual environments with venv

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

4-2-2. Activating the virtual environment

4-2-3. Deactivating the virtual environment

4-2-4. Removing a virtual environment

4-3. Managing virtual environments and dependencies with Poetry

4-3-1. What is Poetry?

4-3-2. Installing Poetry

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

4-4. Comparing venv and Poetry

4-5. Summary

5. Best Practices for Version and Dependency Management

5-1. Create a virtual environment per project

5-1-1. Recommended virtual environment management practices

5-2. Clarifying and managing dependencies

5-2-1. Use requirements.txt

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

5-3. Manage development and production environments separately

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

5-4. Standardizing environments in team development

5-4-1. Standardize the Python version

5-4-2. Use .venv

5-5. Common issues and solutions

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

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

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

5-6. Summary

6. FAQ (Frequently Asked Questions)

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

Solution: Using pyenv

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

If using venv

Removing a Poetry virtual environment

4-2. Creating virtual environments with `venv`

4-3. Managing virtual environments and dependencies with `Poetry`

4-4. Comparing `venv` and `Poetry`

5-2-1. Use `requirements.txt`

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

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

5-4-2. Use `.venv`

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

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

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

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

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

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