The recommended tool for upgrading between &debian; releases is to use the package management tool aptitude. This tool makes safer decisions about package installations than running apt-get directly.

Don't forget to mount all needed partitions (notably the root and /usr partitions) read-write, with a command like: mount -o remount,rw /mountpoint

Next ensure that the APT source entries (in /etc/apt/sources.list) refer to the 'stable' distribution and do not refer to it by its codename (e.g. &oldreleasename;).

It is strongly recommended that you use the /usr/bin/script program to record a transcript of the upgrade session. Then if any problems develop, you will have a log of what happened, and if needed, can provide exact information in a bug report. To start the recording, type: script -a ~/upgrade-to-&releasename;.typescript or similar. Do not put the typescript file in a temporary directory such as /tmp or /var/tmp (files in those directories may be deleted during the upgrade or during any restart).

Next the aptitude package needs to be installed. This is done with:

apt-get install aptitude

Provided that you have a working APT configuration as described above this will install the &releasename; version of aptitude.

First aptitude needs to fetch a list of new and updated packages for the new release. This is done by executing:

aptitude update

Once aptitude has information on all the available packages, the system is almost ready to be fully upgraded.

aptitude -f --with-recommends dist-upgrade

This will perform a complete upgrade of the system, i.e. install the newest available versions of all packages, and resolve all possible dependency changes between packages in different releases. If necessary, it will install some new packages (usually new library versions, or renamed packages), and remove any conflicting obsoleted packages (such as console-tools-libs).

When upgrading from a set of CD-ROMs, you will be asked to insert specific CDs at several points during the upgrade. You might have to insert the same CD multiple times; this is due to inter-related packages that have been spread out over the CDs.

New versions of currently installed packages that cannot be upgraded without changing the install status of another package will be left at their current version (displayed as "held back"). This can be resolved by either using aptitude to choose these packages for installation or by trying aptitude -f install <package>.

The Possible issues during upgrade

Sometimes it's necessary to enable APT::Force-LoopBreak option in APT to be able to temporarily remove an essential package due to a Conflicts/Pre-Depends loop. -o APT::Force-LoopBreak=1 option on

It is possible that a system's dependency structure can be so corrupt as to require manual intervention. Usually this means using dpkg --remove packagename to eliminate some of the offending packages, or aptitude --fix-broken install dpkg --configure --pending

In extreme cases you might have to force re-installation with a command like dpkg --install /path/to/packagename.deb

After fixing things up, you should be able to resume the upgrade by repeating the previously described

During the upgrade, you will be asked questions for configuring or re-configure several packages. When you are asked if any file in the /etc/init.d or /etc/terminfo directories, or the /etc/manpath.config file should be replaced by the package maintainer's version, it's usually necessary to answer `yes' to ensure system consistency. You can always revert to the old versions, since they will be saved with a

If you're not sure what to do, write down the name of the package or file, and sort things out at a later time. You can search in the typescript file to review the information that was on the screen during the upgrade.