Packages & Dependencies Upgrade Guide

Learn how to manage requirements.txt and pyproject.toml updates safely.

Managing Your Dependencies

Ball pythons are opportunistic feeders in the wild, eating whenever prey is available. In captivity, though, keepers maintain strict feeding schedules — typically every 7-14 days for adults. This isn't arbitrary: snakes that eat too frequently develop obesity and liver disease, while snakes that go too long between meals lose body condition and become susceptible to infection. The optimal feeding schedule prevents problems before they become critical, maintaining the snake's health through regular, measured maintenance rather than crisis intervention.

Python applications require similar preventative maintenance for their dependencies. Development teams often treat dependency updates as a chore to be deferred until a major Python or framework upgrade forces the issue. Dependencies that go unupdated for months develop security vulnerabilities, performance degradation, and incompatibilities with the modern ecosystem. This deferred maintenance approach transforms routine updates into high-risk emergency projects. A neglected requirements.txt or pyproject.toml creates the same problems as an improperly fed snake: what should be straightforward maintenance becomes crisis management.

We will look at practical approaches for upgrading Python packages that prioritize long-term maintainability over quick fixes.

Understanding Available Updates

Before we get into modifying our application's state, we should understand what updates are actually available. Pip provides a command specifically for this purpose: pip list --outdated.

Usage

pip list --outdated

In its simplest form, we can run the command without any arguments:

$ pip list --outdated

This will output a list of all packages in your virtual environment that have newer versions available on PyPI. It's worth noting that pip list --outdated is a read-only operation; it contacts PyPI to check for updates but does not modify your environment or install any new code.

You might see output resembling this:

Package    Version  Latest   Type
---------  -------  -------  -----
requests   2.28.0   2.31.0   wheel
pytest     7.1.0    8.0.2    wheel
numpy      1.23.5   1.26.4   wheel

You also may notice that pip shows not only the current and latest versions, but also the package type. This is significant because it helps you understand the installation method used.

The Incremental Update Approach

Before modifying dependencies, it is wise to ensure your tests pass and that the latest 'known good' version of your requirements.txt or lockfile is committed to source control. This provides a safe rollback point if an update introduces a regression.

When faced with a long list of outdated packages, one may wonder: why not update them all at once?

The temptation to run pip install --upgrade -r requirements.txt is strong. That command, however, updates everything in your environment to the latest allowed versions simultaneously. The immediate effect is a fully updated environment; the broader consequence, though, is that if your test suite fails after a global update, determining which specific package update introduced the regression becomes a tedious exercise in isolation.

Instead, we should update packages individually or in tightly related logical groups.

Usage

pip install --upgrade [PACKAGE]

We can update a single package like this:

$ pip install --upgrade requests

Or, for related infrastructure packages, we can pass multiple names:

$ pip install --upgrade psycopg2-binary redis celery

This incremental approach provides a clear path to identifying the source of any issues.

Reviewing Changes

For major package updates, you should always review the maintainer's CHANGELOG.md or release notes on GitHub. Strictly speaking, semantic versioning suggests that breaking changes only occur in major version bumps; in practice, however, unexpected behavior can sometimes slip into minor releases. Look specifically for notes detailing "Breaking Changes" or deprecations.

Verification and Commit Strategy

After each individual package update, verify the changes using your project's automated test suite:

$ pytest

If the tests pass, update your requirements.txt or pyproject.toml and commit immediately with a descriptive message:

$ pip freeze > requirements.txt
$ git add requirements.txt
$ git commit -m "Update requests to 2.31.0"

This ensures that if a regression is discovered later, you have a straightforward path to revert the exact dependency change that caused it.

Modern Dependency Management

There are several approaches to managing Python dependencies beyond simple requirements.txt files:

pip-tools

The pip-tools package provides pip-compile and pip-sync commands for deterministic dependency resolution:

$ pip-compile requirements.in
$ pip-sync requirements.txt

Poetry

Poetry provides a modern approach with lockfiles and dependency resolution:

$ poetry update requests
$ poetry lock

uv

The newer uv tool offers extremely fast package installation and dependency resolution:

$ uv pip compile requirements.in -o requirements.txt
$ uv pip sync requirements.txt

Dealing with Dependency Conflicts

When upgrading a package, you may eventually encounter a resolution conflict. This typically happens because another package in your environment depends on an older version of the package you are trying to update.

Tools like pipdeptree can help visualize dependency relationships:

$ pip install pipdeptree
$ pipdeptree -p requests

Automation Options

There are two major approaches to managing package updates: manual maintenance and automated dependency updates. Depending on your team size and testing infrastructure, one approach may be more useful than the other.

The first approach is manual updating, which we have discussed so far. This provides the most control and forces developers to actively review the changelogs of the dependencies they are upgrading. This is most useful, in my experience, for smaller projects or for major framework upgrades.

The second approach is utilizing automated tools like Dependabot or Renovate. These tools automatically scan your dependency files and open Pull Requests when new package versions are released. This allows your team to review and merge updates continuously — incorporating the testing and verification steps we discussed above — rather than waiting for technical debt to accumulate.

Generally speaking, the automated approach is preferable for long-term maintenance of production applications, provided your test suite is comprehensive enough to catch regressions automatically. Of course, automation does not eliminate the need for review; it merely shifts the burden from discovering updates to evaluating them.