Python is a programming language widely used from beginners to professional engineers because of its simple and readable syntax. However, when you actually start developing, you often run into walls like “this code won’t run for some reason” or “module not found.” In many cases, the cause lies instrong>how packages are managed. In Python, development that relies solely on the standard library is rare, and in many cases you need to install and use external packages (libraries). At that point, if the system for correctly installing, managing, and updating packages isn’t solid, projects can break and collaboration with others can suffer.
The world of management that goes beyond “pip install”
For people new to Python, the idea that “just pip install and you’re done” feels perfectly natural. Indeed, you can add a library that easily. However, as projects multiply,
Package versions clash with other projects
Bugs arise due to old versions
It works everywhere except in production
You’ll encounter such problems. This is a typical trouble caused by insufficient package management knowledge.
What you’ll learn in this article
In this article, we’ll systematically explain Python package management in a way that’s easy for beginners to understand. Specifically, we’ll cover the following topics:
What is a “package” in Python?
How to choose between tools like pip, venv, and Poetry
Why use virtual environments and how to use them
Common errors in package management and how to address them
Frequently asked questions and their answers
Rather than just listing how to use things, we’ll also discuss the background—why you need to do it that way and how to choose.
2. What is a package in Python?
What is a package? Difference from modules
In Python, a “package” is a library with a directory structure that groups multiple modules (Python files) together. In Python, to improve reusability, convenient functions and classes are provided as modules on a per‑file basis, and when they are further organized and structured, they become a “package.” For example, the popular package requests, which handles HTTP communication, contains multiple files (i.e., modules) that operate together as a single package.
Term
Description
Module
.py extension Python file (e.g., math.py)
Package
Folder structure that groups modules together (including __init__.py)
Why use packages
Packages are essential when developing in Python. They allow you to easily introduce and implement features that the standard library cannot cover (such as data analysis, machine learning, web communication) by using external packages. Moreover, the Python community offers a large number of excellent packages that help achieve efficient development and high‑quality code.
What is the Python Package Index (PyPI)?
Most packages are published in the official repository called PyPI (Python Package Index). PyPI is a massive database that aggregates Python packages created and released by developers worldwide, and you can easily install packages from it using the pip command.
pip install numpy
When you run a command like the above, pip looks up PyPI for the numpy package, then downloads and installs it.
How pip installs packages
pip is the official Python package management tool, and it operates in the following sequence.
Consult PyPI (or a specified URL) to retrieve package information
Download the latest or specified version of the package
If there are required dependency packages, install them simultaneously
Store them in the local environment’s site-packages folder
After installation, you can use it in a Python script as follows.
import numpy as np
arr = np.array([1, 2, 3])
print(arr)
Summary: Understanding packages is the first step to avoiding trouble
By understanding how packages work in Python, you can prevent common issues such as “module not found” or “does not work with an older version.” In the next section, we will delve deeper into the fundamental tool “pip” for installing and managing these packages.
3. Basic Package Management Tool “pip”
What is pip?
pip is the most fundamental package management tool in Python. It has been included by default since Python 3.4, so you can use it without any additional configuration. Its main functions are installing, uninstalling, upgrading, and listing external packages, among others. pip‘s name is said to be an abbreviation of Pip Installs Packages, and as the name suggests, it is a command-line tool for installing Python packages.
Basic pip Commands and Usage
Below is a summary of the most commonly used pip commands and their purposes.
Command
Description
pip install package_name
Install a package
pip uninstall package_name
Uninstall (remove) a package
pip list
Display a list of currently installed packages
pip show package_name
Show detailed information for the specified package
pip freeze
Display installed packages and their versions (used in requirements.txt discussed later)
pip install -r requirements.txt
Bulk install multiple packages (convenient for sharing projects)
Example usage (command line):
pip install requests
pip list
pip uninstall requests
What is requirements.txt?
requirements.txt is a file that lists the packages used in a project along with their version information. It is extremely handy when developing with multiple people or moving a project to a different environment. It looks like this:
requests==2.31.0
numpy>=1.24
Using this file, you can bulk install with the following command:
pip install -r requirements.txt
Upgrading and Specifying Versions
pip also supports upgrading packages and specifying versions.
When upgrading to the latest version:
pip install --upgrade package_name
When installing a specific version:
pip install package_name==1.2.3
Dependency Issues and Cautions
pip is simple and easy to use, but it has a weakness when it comes to managing complex dependencies. For example, the version required by one package may conflict with the version required by another package. As a result,
Installation fails
Runtime errors occur
Other packages break
These issues can lead to trouble such as the above. To avoid them, using virtual environments (venv) discussed later or more advanced tools (like Poetry) is effective.
Summary: pip is fundamental, but don’t overestimate it
pip is the most basic tool in Python development, and for small scripts or solo projects it can be sufficient on its own. However, in projects where dependencies become complex or development environments differ, there are cases where managing with only pip becomes difficult. The next section will look in detail at how to use virtual environments (venv) to solve those problems.
4. Why Use Virtual Environments (venv) and How to Use Them
Why a Virtual Environment Is Needed?
In Python development, the packages and versions you use often differ from project to project. For example:
Project A uses Django 3.2
Project B uses Django 4.0
In such cases, installing packages system‑wide can cause the problem that upgrading one will break the other. To avoid this, you introduce a “virtual environment”. Using a virtual environment allows independent package management per project, enabling development that doesn’t interfere with other environments.
What Is venv?
venv is Python’s built‑in virtual environment creation tool. It’s included with Python 3.3 and later, so no extra installation is needed. With venv, you can create an isolated Python runtime and package set for each project.
Basic venv Operations
1. Creating a Virtual Environment
Run the following command inside any project folder.
python -m venv venv
This command creates a folder named venv and sets up the virtual environment (the folder name is arbitrary, but venv is conventionally used).
2. Activating the Virtual Environment
Windows：
venvScriptsctivate
macOS / Linux：
source venv/bin/activate
When activation succeeds, the terminal prompt will show something like (venv) at the beginning.
3. Deactivating the Virtual Environment
To exit the virtual environment, run the following command.
deactivate
4. Deleting the Virtual Environment
The virtual environment is just a folder, so you can simply delete the venv directory.
rm -r venv # mac/Linux
rd /s /q venv # Windows
Building a Safe Environment with venv + pip
When you run pip install with the virtual environment activated, packages are installed inside the virtual environment and do not affect the system as a whole. This prevents adverse effects on production or other projects.
source venv/bin/activate
pip install requests
Libraries installed in this state become unavailable once you leave the virtual environment (deactivate).
Integration with IDEs (e.g., VSCode)
Modern editors like Visual Studio Code (VSCode), widely used by engineers, can automatically detect virtual environments and switch the Python interpreter per project. Combined with venv, this greatly improves development efficiency and environment stability.
Summary: Virtual Environments Are a Fundamental Skill for Python Development
Python’s virtual environments (venv) are a must‑have skill for avoiding package version conflicts and environment issues. Using them together with pip lets you set up a safe and reproducible development environment.
5. Using the Dependency Management Tool “Poetry”
Why pip and venv alone are not enough
pip and venv are fundamental tools for Python development, but as projects become more complex or require team collaboration, the following challenges arise.
When dependencies increase, requirements.txt tends to be managed manually
Reproducing package states across multiple environments is difficult
Publishing and building packages becomes cumbersome
The tool that addresses these challenges is the package & project management tool called Poetry (Poetry).
What is Poetry?
Poetry is a modern tool that can manage a Python project’s dependencies, virtual environments, and package publishing in an integrated way. It has the following features:
Centralizes dependency information in pyproject.toml
Automatically creates and manages virtual environments
No need to manually configure pip or venv
Package building and publishing are also possible (PyPI support)
By using Poetry, you can achieve a development environment that lets you focus on writing code.
How to install Poetry
Poetry is installed via the official script. Running the following command installs it according to your OS.
It interactively registers dependencies and generates a pyproject.toml.
3. Adding and removing packages
Add (install):
poetry add requests
Remove:
poetry remove requests
4. Automatic creation and activation of virtual environments
Poetry automatically creates a virtual environment when you add dependencies. You can enter that environment with:
poetry shell
Within the virtual environment, Python and pip are available.
5. Ensuring reproducibility with lock files
Poetry records dependency information in a file called poetry.lock. This allows other developers to reproduce exactly the same environment.
poetry install
This command builds an exact environment based on pyproject.toml and poetry.lock.
The role of pyproject.toml
In Poetry, instead of using the traditional setup.py or requirements.txt, all configuration is consolidated into a single file called pyproject.toml. Example:
[tool.poetry]
name = "myproject"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
[tool.poetry.dependencies]
This structure enables an ideal environment where the project’s state is managed in code.
Summary: Poetry is a strong ally for modern development
Poetry is a powerful development support tool that frees you from the cumbersome management of traditional pip and venv. It is especially recommended for the following people:
Those who develop with multiple people
Those who want to clarify package dependencies
Those who want to automate virtual environment creation
Those who plan to publish packages in the future
6. Comparison with Other Tools (Poetry vs pipenv vs conda)
Package management tools should be chosen according to their use case
In addition to pip and venv, there are several other handy tools for Python package management. The three most common are listed below:
Poetry：A modern tool strong in dependency management and package building
Pipenv：A middle ground between pip and venv. Beginner-friendly but somewhat unstable
conda：Strong for building environments for data science, and can manage non-Python packages as well
Each has its strengths and weaknesses, so choosing the right tool based on the project’s goals and development style is important.
Comparison table of each tool
Below is a table summarizing the main differences among Poetry, Pipenv, and conda:
Item
Poetry
Pipenv
conda
Virtual environment management
Automatically created and managed
Automatically created and managed
Custom environment (conda)
Dependency specification
pyproject.toml & poetry.lock
Pipfile & Pipfile.lock
environment.yml
Support for non-Python languages
✕
✕
◯（R, C, Java, etc.）
Package build & publishing
◯（PyPI support）
△（cannot publish）
✕
Cross‑platform support
◯
△（some bugs）
◯
Modernity & consistency
◎
○
△（somewhat heavy）
Primary use cases
Web development & publishing
Beginner‑friendly development
Data analysis & scientific computing
Features of each tool and suitable use cases
Poetry: Implements best practices for developers
Poetry places the greatest emphasis on Python development as a project. It handles dependency management, virtual‑environment automation, and package publishing in a unified way, making it very popular among intermediate to advanced users. Who it’s suited for:
People who develop full‑scale Python applications such as web apps or APIs
People who want to publish their own packages to PyPI
People who value reproducibility of configuration files in team development
Pipenv: A tool aiming to take the best of pip and venv
Pipenv integrates the functionality of pip and venv and provides a UI that is easy for beginners to use. It manages dependencies with its own Pipfile format and automatically creates a virtual environment. However, its update frequency has slowed, and unstable behavior and bugs have been reported in some environments, leading many to switch to Poetry recently. Who it’s suited for:
Beginners who have become somewhat familiar with pip and venv
People who want to start with it for learning or small‑scale projects
People who prefer fewer commands and an intuitive workflow
conda: Manages extensive environments including non‑Python packages
conda is the package manager included in the Anaconda distribution, and it can manage environments not only for Python but also for R, C, and others. It is especially valued in scientific computing and data‑analysis settings. Its dependency‑resolution capabilities are extremely strong, making it easy to handle complex libraries such as NumPy, TensorFlow, OpenCV, and the like—a major advantage. Who it’s suited for:
People who want to work in data science, machine learning, or statistical analysis
People who need to manage languages other than Python simultaneously
People struggling with package dependencies on Windows
Guidelines for choosing
When in doubt, consider the following to make a choice easier.
Data analysis / multi‑language environment → conda
Summary: Choosing the right tool for the purpose is the key to success
Python package management can be confusing because there are so many tools. However, once you clarify “what you intend to use it for”, the optimal tool becomes apparent. Poetry, Pipenv, and conda each have strengths and suitable scenarios; selecting the one that matches your development style and team setup enables a smoother, more reproducible development environment.
Even if you know how to use package management tools, it’s meaningless if you don’t know how to start using them in an actual project. Here, we explain the steps to set up a project in two patterns so that beginners can proceed without getting lost.
pip + venv Basic setup method
Poetry Smart setup method
Pattern 1: Project Setup with pip + venv
The most basic method, recommended for people who are just starting with Python. Step 1: Create the project folder
mkdir my_project
cd my_project
Step 2: Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows, use venv\Scripts\activate
Step 3: Install required packages
pip install requests numpy
Step 4: Write dependency packages to requirements.txt
pip freeze > requirements.txt
Step 5: Deactivate the virtual environment
deactivate
With this setup, other developers can reproduce the environment based on requirements.txt:
With Poetry, you no longer need to manually manage virtual environments or dependencies, enabling more efficient development. Step 1: Initialize the project
poetry new my_project
cd my_project
This automatically generates a structure like the following.
Poetry automatically creates a virtual environment at this point and records the dependencies in pyproject.toml and poetry.lock. Step 3: Enter the virtual environment (optional)
poetry shell
Step 4: How others can reproduce the environment When sharing the project, the same environment can be reproduced with just the following command:
poetry install
With this, all dependencies are installed precisely, and the virtual environment is automatically created.
Which Method Should You Choose?
Situation
Recommended Tool
Learning purpose, want to get familiar with Python first
pip + venv
Team development, need explicit and automated dependency management
Poetry
Planning to publish or distribute a library
Poetry
Lightweight temporary scripts or testing
pip (no virtual environment) is also OK
Supplement: Integration with IDEs like VSCode
IDEs such as Visual Studio Code and PyCharm have features that automatically recognize virtual environments and Poetry’s virtual environments. When you open the project folder, the appropriate Python interpreter is selected, so you can switch environments in the editor without confusion.
Summary: Consistent Environment Setup Is the Key to Quality and Reproducibility
In Python development, creating an environment that runs the same for anyone is extremely important. As shown here, using pip + venv or Poetry correctly makes that possible.
8. Common Errors and Solutions
Why are errors prone to occur in package management?
While Python is a flexible language, unexpected errors often arise due to package versions, dependencies, and differences in virtual environments. In particular, there are several common trouble patterns that beginners tend to fall into. Here we introduce typical errors and their solutions.
Error 1: ModuleNotFoundError – Module not found
Error details:
ModuleNotFoundError: No module named 'requests'
Cause:
Package is not installed
Virtual environment is not activated
Running in a different Python environment
Solution:
Verify that the package was installed in the correct environment
pip install requests
Check that the virtual environment is active and reactivate if necessary
source venv/bin/activate # or venvScriptsctivate
If running in an IDE such as VSCode, verify the selected Python interpreter
Error 2: Permission denied or access denied when using pip install
Attempting to install the package into the global environment
Running as a user without administrative privileges
strong>
Ensure you are working inside a virtual environment
If you must run in the global environment, add the --user option
pip install --user package_name
In Mac/Linux, use sudo for operations that require admin rights (not recommended)
Error 3: Version conflicts (dependency collisions)
Error details (example):
ERROR: Cannot install X==1.2.0 and Y==2.0.0 because these package versions have incompatible dependencies.
Cause:
Multiple packages being installed simultaneously depend on different versions of the same library
Solution:
Use tools like pipdeptree to visualize and inspect dependencies
Use tools such as Poetry or conda that automatically resolve dependency consistency
If conflicts cannot be resolved, separate them into different virtual environments
Error 4: Installation from requirements.txt fails
Error details:
ERROR: Could not find a version that satisfies the requirement X==1.0.0
Cause:
The version listed in requirements.txt does not exist or has been deprecated
Incompatible with your Python version
Solution:
Check PyPI to confirm the package and version exist
Specify a version compatible with your Python version
When using Poetry, run poetry update to update to a consistent set of dependencies
Error 5: Virtual environment does not work correctly or cannot be activated
Error details (example):
source: command not found
Cause:
Using Unix-style commands on Windows
Incorrect path when creating the virtual environment
Solution:
Check the activation command for the virtual environment appropriate to your OS
# macOS / Linux
source venv/bin/activate
# Windows
venvScriptsctivate
If the environment is corrupted, delete it and recreate it
rm -r venv
python -m venv venv
Note: Issues when pip version is outdated
If pip itself is outdated, it may not support the latest PyPI specifications, causing installation failures. Solution:
pip install --upgrade pip
Regularly upgrading helps prevent future errors.
Summary: Errors aren’t scary once you understand the “mechanics”
Most package-management errors stem from “environment,” “dependencies,” or “Python version.” Instead of rushing to apply ad‑hoc fixes, reading the error messages, understanding the underlying mechanisms, and responding accordingly is the fastest path to mastering Python.
9. Frequently Asked Questions (FAQ)
Q1. Should I use pip or Poetry?
A. For small scripts or learning projects, the combination of pip and venv is sufficient. However, when developing with multiple people or when package dependencies become complex, Poetry is recommended because it makes dependency management easier and offers higher reproducibility.
Q2. Is it mandatory to use a virtual environment?
A. It’s not required, but it is strongly recommended. Without a virtual environment, you can affect the system-wide Python environment, causing dependency conflicts with other projects and other issues.
Q3. What is the difference between pyproject.toml and requirements.txt?
A.
requirements.txt: a simple text-format dependency list used by pip
pyproject.toml: a structured configuration file used by tools like Poetry (dependencies + metadata)
requirements.txt emphasizes reproducible installations, while pyproject.toml is suited for overall project configuration management.
Q4. Which is more mainstream, pipenv or Poetry?
A. Currently, Poetry is being actively developed and outperforms pipenv in reliability and features. pipenv was popular for a while, but due to stalled updates and growing bug reports, migration to Poetry is underway.
Q5. Can conda and pip be used together?
A. Generally they can be used together, but you need to be careful about dependency consistency. In a conda environment, install packages with conda whenever possible, and only use pip for packages that are not available in conda to avoid trouble.
Q6. I have created too many virtual environments and managing them is difficult. What should I do?
A. Using Poetry automates creation and deletion of virtual environments, greatly reducing manual management effort. Also, you can use the following commands to list and locate virtual environments:
poetry env list
poetry env remove <environment_name>
Q7. Should requirements.txt and pyproject.toml be included in Git?
A. Yes, they are essential files that must be included to ensure project reproducibility. Including them allows other developers to easily recreate the same environment, making team development smoother.
Q8. Can packages be managed separately for production and development environments?
A. With Poetry you can clearly separate and manage dependencies for development and production. For example, test frameworks can be installed only for development:
poetry add pytest --group dev
This way, unnecessary tools are not installed in the production environment.
Q9. What should I do when an error occurs?
A. First, calmly read the error message and check the following points.
Is the virtual environment activated?
Is the Python version you are using compatible?
Does the relevant package exist on PyPI?
Also, please refer to the “8. Common Errors and Solutions” section.
Q10. What should be considered when multiple people develop a project?
A. The most important thing is to make the environment reproducible. Enforcing the following helps prevent trouble:
Use virtual environments
Share requirements.txt or pyproject.toml / poetry.lock
Specify a clear Python version (e.g., Python 3.10 or higher)
Using Poetry makes it relatively easy to achieve these.
