# Mastering pip and PyPI: A Guide to Python Package Management
URL: https://madhudadi.in/blog/posts/pip-and-pypi-install-upgrade-and-manage-packages
Published: 2026-06-10
Tags: python, setup
Read time: 42 min
Difficulty: beginner
> Learn pip and PyPI from scratch: install packages, upgrade packages, uninstall packages, freeze requirements, fix common pip errors, and avoid global install mistakes.# pip and PyPI: Install, Upgrade, Uninstall, and Manage Python Packages

## Quick Answer

`pip` installs Python packages. PyPI is the main public package index where many Python packages are published.

Beginner rule: install packages inside a virtual environment and run pip through Python.

Windows:

```powershell
py -m pip install package-name
```

macOS:

```bash
python3 -m pip install package-name
```

Last verified: June 9, 2026. Current pip documentation is in the `v26.1.x` series.

## Official Links

- pip documentation: https://pip.pypa.io/en/stable/
- pip installation docs: https://pip.pypa.io/en/stable/installation/
- pip user guide: https://pip.pypa.io/en/stable/user_guide/
- pip configuration docs: https://pip.pypa.io/en/stable/topics/configuration/
- PyPI: https://pypi.org/
- Python packaging guide: https://packaging.python.org/

## What You Will Learn

By the end, you should be able to:

- explain what pip does
- explain what PyPI is
- install packages on Windows and macOS
- upgrade and uninstall packages
- create and use `requirements.txt`
- avoid global package mistakes
- fix common pip errors

## 1. What pip Does

Python includes a standard library, but many useful tools are separate packages.

Examples:

```text
pandas
matplotlib
requests
jupyterlab
pytest
```

`pip` downloads and installs these packages.

## 2. What PyPI Is

PyPI is the Python Package Index:

```text
https://pypi.org/
```

When you run:

```bash
python -m pip install requests
```

pip usually downloads `requests` from PyPI.

## 3. Check pip Before Installing

Windows PowerShell:

```powershell
py -m pip --version
```

If `py` is unavailable but `python` works:

```powershell
python -m pip --version
```

macOS:

```bash
python3 -m pip --version
```

Linux:

```bash
python3 -m pip --version
```

The output shows both pip version and the Python environment it belongs to.

## 4. Create A Safe Practice Environment

Do not install learning packages globally by default.

Windows:

```powershell
mkdir pip-practice
cd pip-practice
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
```

macOS:

```bash
mkdir pip-practice
cd pip-practice
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

After activation, `python` points to the environment's Python.

Check:

```bash
python -c "import sys; print(sys.executable)"
```

The path should contain `.venv`.

## 5. Install A Package

Install `requests`:

```bash
python -m pip install requests
```

Test it:

```bash
python -c "import requests; print(requests.__version__)"
```

Install multiple packages:

```bash
python -m pip install pandas matplotlib
```

## 6. Install A Specific Version

Sometimes a project needs a specific package version.

```bash
python -m pip install "pandas==2.3.0"
```

Use quotes because some shells treat symbols specially.

For learning, latest stable packages are usually fine. For projects, record versions in `requirements.txt`.

## 7. Upgrade A Package

Upgrade one package:

```bash
python -m pip install --upgrade requests
```

Upgrade pip itself:

```bash
python -m pip install --upgrade pip
```

## 8. Uninstall A Package

```bash
python -m pip uninstall requests
```

pip asks for confirmation.

Use this carefully inside the right environment.

## 9. List Installed Packages

```bash
python -m pip list
```

Show package details:

```bash
python -m pip show pandas
```

## 10. Create requirements.txt

`requirements.txt` records the packages needed to recreate a project.

```bash
python -m pip freeze > requirements.txt
```

Example file:

```text
pandas==2.3.0
matplotlib==3.10.0
requests==2.32.0
```

Commit `requirements.txt` to Git. Do not commit `.venv`.

## 11. Install From requirements.txt

When someone downloads your project:

Windows:

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

## 12. Common pip Errors And Fixes

### `pip is not recognized`

Use Python to run pip:

```powershell
py -m pip --version
```

or:

```bash
python3 -m pip --version
```

### `No module named pip`

Try:

```bash
python -m ensurepip --upgrade
python -m pip install --upgrade pip
```

On Linux, you may need:

```bash
sudo apt install python3-pip python3-venv
```

### `Permission denied`

You are probably installing globally.

Fix it by using a virtual environment:

```bash
python -m venv .venv
```

Then activate it and install again.

### `externally-managed-environment`

This commonly appears on modern Linux distributions when pip tries to modify system-managed Python.

Beginner-safe fix:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install package-name
```

Avoid `--break-system-packages` unless you fully understand the risk. It can damage the system Python package boundary.

### Network, proxy, timeout, or SSL errors

Common messages:

```text
ReadTimeoutError
ProxyError
SSLError
certificate verify failed
```

First check whether your internet connection or office/college network blocks package downloads.

Then upgrade pip inside your virtual environment:

```bash
python -m pip install --upgrade pip
```

If your network requires a proxy, ask your network administrator for the proxy URL and use:

```bash
python -m pip install --proxy http://user:password@proxy.example.com:8080 package-name
```

If your organization uses a custom certificate, ask for the certificate file and use:

```bash
python -m pip install --cert path/to/company-ca.pem package-name
```

Avoid random `--trusted-host` fixes from forums. They weaken package download security and usually hide the real certificate problem.

### Package installs but import fails

Check which Python is running your code:

```bash
python -c "import sys; print(sys.executable)"
```

Then install using that same Python:

```bash
python -m pip install package-name
```

## 13. Windows And macOS Command Comparison

| Task | Windows | macOS |
| --- | --- | --- |
| Check Python | `py --version` | `python3 --version` |
| Check pip | `py -m pip --version` | `python3 -m pip --version` |
| Create venv | `py -m venv .venv` | `python3 -m venv .venv` |
| Activate venv | `.\.venv\Scripts\Activate.ps1` | `source .venv/bin/activate` |
| Install package after activation | `python -m pip install requests` | `python -m pip install requests` |

## Practice Task

Create a fresh environment and install `requests`.

```bash
python -m pip install requests
python -c "import requests; print(requests.__version__)"
python -m pip freeze > requirements.txt
```

If all three commands work, pip is working correctly.

## FAQ

### Should I type `pip install` or `python -m pip install`?

Use `python -m pip install` after activating a virtual environment. On Windows before activation, use `py -m pip`. On macOS before activation, use `python3 -m pip`.

### Is PyPI safe?

PyPI is the main public package index, but anyone can publish packages. Install known packages, check spelling, and avoid random packages from tutorials you do not trust.

### Should I install packages globally?

Avoid it for projects. Use a virtual environment so each project has its own dependencies.

### Should I use pip or uv?

Learn pip because it is fundamental. Use uv for faster modern project workflows after you understand pip and virtual environments.

## Final Checklist

Windows:

```powershell
py -m pip --version
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install requests
python -c "import requests; print(requests.__version__)"
```

macOS:

```bash
python3 -m pip --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -c "import requests; print(requests.__version__)"
```

If this works, you can install Python packages safely.