Python package management and module import guide

When writing Python, package management and module import are two things that you deal with every day. If used well, the environment will be clean and the code will be clear; if used incorrectly, you will frequently run intoModuleNotFoundError, and even fell into the situation of "this machine can run, but that machine reports an error". This guide will use official recommendations in a way that novices can understand.pip, virtual environments, alternativescondaGo over the behind-the-scenes rules of module import to help you avoid common pitfalls.

1. Official first choice: pip package management tool

1.1 Why pip?

pipIt is Python's official package management tool. It mainly downloads, installs, upgrades, and uninstalls various packages from PyPI (Python Package Index, the world's largest Python third-party package warehouse).

The good news is: Python 3.4 and above versions have built-in pip, so there is no need to run it manually.get-pip.py. If you accidentally lost it or the version is too old, you can fix it with the following command:

python -m ensurepip --upgrade

1.2 Quick check of commonly used commands

The following commands cover 80% of usage scenarios. Note: All commands are usedpython -m pipform, why this is more secure will be explained later.

# 安装最新稳定版
python -m pip install requests

# 安装指定版本（注意是两个等号）
python -m pip install requests==2.31.0

# 安装兼容指定主版本的最新版（波浪号）
python -m pip install requests~=2.31.0

# 只升级到次要版本/补丁版本（更安全的升级策略）
python -m pip install --upgrade-strategy=only-if-needed requests

# 强制升级到最新版
python -m pip install --upgrade requests

# 卸载包（加 -y 跳过确认）
python -m pip uninstall requests -y

# 列出已安装的包（加 --outdated 查看可更新的包）
python -m pip list
python -m pip list --outdated

# 查看包的详细信息（版本、位置、依赖关系等）
python -m pip show requests

# 导出当前环境所有依赖到 requirements.txt
python -m pip freeze > requirements.txt

# 从 requirements.txt 批量安装依赖
python -m pip install -r requirements.txt

1.3 What should I do if multiple versions of Python coexist?

Do you have Python 3.8, 3.10, or even Python 2.7 installed on your computer? Please forget to type directlypip、pip3For this kind of vague command, using "target interpreter -m pip" is the most reliable way:

# 明确调用 Python 3.10 的 pip
python3.10 -m pip install requests

# Windows 下也可以使用 py 启动器，更友好
py -3.10 -m pip install requests
# 偶尔维护老项目时：
py -2 -m pip install six

By doing this, you will always know which Python environment you are packaging into.

2. Artifact for isolating dependencies: virtual environment

2.1 Why use a virtual environment?

Let's say you maintain two projects at the same time:

Project A depends onrequests==2.25(Requires running under Python 3.7)
Project B dependenciesrequests==3.x(Requires Python 3.12)

If all packages are installed in the global environment, conflicts will inevitably occur. Virtual environment is to give each project an independent Python sandbox, and install dependencies separately without interfering with each other.

2.2 Python native venv (recommended for lightweight projects)

Python 3.3 or above has built-invenvModule, no additional installation required:

# 1. 在项目根目录创建虚拟环境（myenv 可以换成你喜欢的名字）
python -m venv myenv

# 2. 激活虚拟环境
## Windows CMD
myenv\Scripts\activate.bat
## Windows PowerShell（首次可能需要启用脚本执行权限）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
myenv\Scripts\Activate.ps1
## Unix/macOS（bash/zsh）
source myenv/bin/activate

# 激活后，终端提示符前会出现 (myenv)，表示当前环境已切换
# 此时直接使用 pip 安装即可，不需要加 python -m 前缀了

# 3. 退出虚拟环境
deactivate

2.3 Correct usage of requirements.txt

pip freezeWill list all packages in the current environment (including indirect dependencies), suitable for deployment/release scenarios. However, in the development stage, it is recommended to only write the core packages that the project directly depends on, which is clearer and easier to maintain:

# 开发版 requirements.txt 示例（只包含直接依赖）
requests>=2.31.0,<3.0.0
pandas>=2.0.0

This can avoid unnecessary changes due to minor version changes in indirect dependencies, and at the same time cooperate withpip install -r requirements.txtAll indirect dependencies will still be automatically resolved and installed.

3. Alternative for data science players: Anaconda

If you are mainly engaged in data analysis and machine learning, you will definitely have heard of Anaconda. It is pre-installed with 1500+ commonly used scientific computing packages such as NumPy, Pandas, Matplotlib, etc.condaThe tool can not only manage Python packages, but also different versions of Python interpreters and C/C++ libraries.

3.1 Installation suggestions

It is recommended to install Miniconda (contains only Python and conda, small size and high flexibility), and then manually install the scientific computing package as needed.
Installation package can be downloaded from Anaconda 官网 graphical installer.
Windows users: Although checking "Add Anaconda to PATH" is convenient for novices to use directly, it may conflict with other software; advanced users can leave it unchecked and activate conda through Anaconda Prompt or manually.

3.2 conda high-frequency commands

# 1. 创建指定 Python 版本的环境
conda create --name mydataenv python=3.10

# 2. 激活环境
conda activate mydataenv

# 3. 安装包（优先用 conda 安装，找不到的更再用 pip）
conda install numpy pandas matplotlib

# 4. 搜索可安装的包
conda search tensorflow

# 5. 导出/导入环境（.yml 文件比 requirements.txt 信息更全）
conda env export > environment.yml
conda env create -f environment.yml

# 6. 退出/删除环境
conda deactivate
conda remove --name mydataenv --all

4. Behind-the-scenes rules for module import: search path

Sometimes the package is clearly installed, but the import error messageModuleNotFoundError, most likely because Python cannot find the installation location of the package.

4.1 View the current search path

You can see this by running a simple Python code:

import sys
print(sys.path)

When Python imports a module, it will search in these paths from top to bottom, and will stop once it finds a matching module.

4.2 How to add a path temporarily or permanently

If your custom modules are not in the project root directory, there are two ways to get Python to find them.

Method 1: Temporarily add during runtime (only valid for the current script/interactive window)

import sys
import os

# 路径拼接推荐用 os.path，避免跨平台分隔符问题
custom_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'custom_modules'))
sys.path.append(custom_path)

# 现在就可以导入了
import my_custom_module

Method 2: Add permanently (valid for all Python sessions)

By setting environment variablesPYTHONPATHaccomplish:

# Unix/macOS（添加到 ~/.bashrc 或 ~/.zshrc 实现永久生效）
export PYTHONPATH="/Users/xxx/custom_modules:$PYTHONPATH"

# Windows CMD（临时生效）
set PYTHONPATH=C:\Users\xxx\custom_modules;%PYTHONPATH%
# Windows PowerShell（永久生效需在系统环境变量里添加）
$env:PYTHONPATH = "C:\Users\xxx\custom_modules;$env:PYTHONPATH"

5. Pitfall avoidance guide: Solving common problems

5.1 What should I do if the installation fails?

Network Timeout: Domestic users recommend configuring Tsinghua, Alibaba and other mirror sources, which are very fast.

# 临时使用镜像
python -m pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple
# 永久配置镜像
python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Insufficient permissions: Windows runs the terminal as administrator; Unix/macOS can add--userInstall to the user directory (but a virtual environment is more recommended).
```
python -m pip install --user requests
```
Compilation error: Some packages depend on C extensions, Windows can install Visual Studio Build Tools; Unix/macOS installs gcc/clang; or install precompiled binary packages directly through conda.

5.2 Three-step troubleshooting of import errors

Check whether the package is installed:python -m pip show package_name
Check the case carefully: Python is case-sensitive.import Requestswill fail.
Confirm that the package installation location issys.pathMedium: Print path list for manual comparison.

6. Best practices that novices must follow

One virtual environment for each project, fundamentally eliminating dependency conflicts.
usepython -m piprather than nakedpip, to avoid the confusion of multiple versions.
Domestic users can configure permanent mirror sources, which greatly improves the installation experience.
Maintain concise requirements.txt during development and reuse it during releasepip freezeGenerate complete dependency files.
Do not submit the virtual environment folder to Git - in.gitignoreAdd inmyenv/(or your environment name).

By mastering these, you can easily control Python's package management and module import, and keep the development environment clean and efficient~

#Python package management and module import guide

#1. Official first choice: pip package management tool

#1.1 Why pip?

#1.2 Quick check of commonly used commands

#1.3 What should I do if multiple versions of Python coexist?

#2. Artifact for isolating dependencies: virtual environment

#2.1 Why use a virtual environment?

#2.2 Python native venv (recommended for lightweight projects)

#2.3 Correct usage of requirements.txt

#3. Alternative for data science players: Anaconda

#3.1 Installation suggestions

#3.2 conda high-frequency commands

#4. Behind-the-scenes rules for module import: search path

#4.1 View the current search path

#4.2 How to add a path temporarily or permanently

#Method 1: Temporarily add during runtime (only valid for the current script/interactive window)

#Method 2: Add permanently (valid for all Python sessions)

#5. Pitfall avoidance guide: Solving common problems

#5.1 What should I do if the installation fails?

#5.2 Three-step troubleshooting of import errors

#6. Best practices that novices must follow