How to Downgrade a Python Package with pip

Sometimes a new package version breaks your code. You update a library and suddenly your project stops working. This is a common problem in Python.

The good news is that you can fix it fast. With pip, you can downgrade a package to an older version in seconds.

This guide shows you exactly how to downgrade a Python package with pip. It covers the safe steps, the commands, and the common mistakes to avoid.

Why You Might Need to Downgrade a Package

New versions usually bring improvements. But they can also introduce bugs or breaking changes.

Here are the most common reasons to downgrade:

A recent release removed a function your code depends on. Another package in your project only works with an older version. A bug in the latest version causes crashes or wrong results. Or your production server runs an older version and you need to match it.

In all these cases, downgrading is the quickest fix. It lets you keep working while you plan a proper upgrade later.

Check the Current Version First

Before you change anything, find out which version you have now.

Run this command in your terminal:

pip show requests

The output shows useful details, including the version number:

Name: requests
Version: 2.31.0
Summary: Python HTTP for Humans.
Home-page: https://requests.readthedocs.io
Author: Kenneth Reitz
License: Apache 2.0
Location: /usr/lib/python3/dist-packages
Requires: certifi, charset-normalizer, idna, urllib3

You can also list all installed packages with their versions:

pip list

This gives you a full picture of your environment. It helps you spot version conflicts early.

Find the Version You Want

Next, decide which version you need. You can check all available versions on the Python Package Index (PyPI).

Run this command to see every released version:

pip index versions requests

The output lists the available versions:

requests (2.31.0)
Available versions: 2.31.0, 2.30.0, 2.29.0, 2.28.2, 2.28.1, 2.28.0, 2.27.1

Pick the version that works for your project. If you are unsure, choose the last version that worked before the problem started.

Downgrade the Package with pip

Now you are ready to downgrade. The command is simple.

Use pip install with the package name and the target version:

pip install requests==2.28.2

Pip will uninstall the current version and install the older one. You will see output like this:

Collecting requests==2.28.2
  Downloading requests-2.28.2-py3-none-any.whl (62 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.3/62.3 kB 1.2 MB/s eta 0:00:00
Installing collected packages: requests
  Attempting uninstall: requests
    Found existing installation: requests 2.31.0
    Uninstalling requests-2.31.0:
      Successfully uninstalled requests-2.31.0
Successfully installed requests-2.28.2

That is all it takes. The package is now downgraded.

Always use the double equals sign (==) to pin an exact version. This avoids surprises.

Downgrade Inside a Virtual Environment

It is best to work inside a virtual environment. This keeps your project isolated from the system Python.

Create and activate one like this:

# Create a virtual environment
python -m venv myenv

# Activate it on Linux or macOS
source myenv/bin/activate

# Activate it on Windows
myenv\Scripts\activate

Then run the downgrade command as usual. Your global Python stays untouched.

This is a safe practice for every project. It prevents version conflicts between different apps.

Verify the Downgrade Worked

After the install finishes, confirm the change. Run the show command again:

pip show requests

The version field should now show the older number:

Name: requests
Version: 2.28.2

You can also check it from inside Python. This is handy for quick tests:

# Import the package and print its version
import requests

print(requests.__version__)

The output confirms the installed version:

2.28.2

If both checks match, the downgrade was successful.

Common Errors and How to Fix Them

Sometimes the command fails. Here are the most common problems.

Permission denied. This happens when you install to the system Python. Use pip install --user or activate a virtual environment instead.

No matching distribution found. The version you typed may not exist. Check the version list again with pip index versions.

Dependency conflicts. Another package may require the newer version. Pip will warn you. In that case, downgrade the conflicting package too, or use a virtual environment per project.

If pip itself is old, upgrade it first with python -m pip install --upgrade pip. This fixes many odd errors.

Pin the Version in requirements.txt

After a successful downgrade, save the version. This keeps your environment stable for others.

Add the exact version to your requirements file:

# requirements.txt
requests==2.28.2

Then anyone can reproduce your setup with a single command:

pip install -r requirements.txt

This step is very important for teams and deployments. It stops the same problem from coming back.

Downgrade Multiple Packages at Once

You can also downgrade more than one package in a single command.

Just list them with their versions:

pip install requests==2.28.2 urllib3==1.26.15

Pip handles each one in order. This is useful when packages depend on each other.

Conclusion

Downgrading a Python package with pip is quick and easy. The key command is pip install package==version.

Always check your current version first. Then pick the right older release. Work inside a virtual environment to stay safe. Verify the change with pip show. Finally, pin the version in your requirements file.

Follow these steps and you can fix version problems in minutes. Your project will run smoothly again, and you will avoid the same issue in the future.