Rename Debian Package Files Safely with dpkg-name

dpkg-name renames an awkward Debian package file to the full name recorded in its control data, such as widget_1.4-2_amd64.deb. The examples use dpkg-name 1.22.6 from the installed dpkg-dev package. Allow about fifteen minutes, plus time to check the directory before changing a real archive.

You need a shell, a readable Debian package file, and permission to rename files in its directory. Normal renaming does not need elevated privileges. Use sudo only if the directory permissions genuinely require it, and inspect the command carefully before doing so.

1. Check the installed command

Confirm which executable will run and record its version. These are read-only checks:

$ command -v dpkg-name
/usr/bin/dpkg-name
$ dpkg-name --version
Debian dpkg-name version 1.22.6.

The installed package version can include a distribution revision even when the program reports only the upstream dpkg version:

$ dpkg-query -W -f='${Package} ${Version}\n' dpkg-dev
dpkg-dev 1.22.6ubuntu6.6

Checkpoint: if dpkg-name is missing, stop and install or repair dpkg-dev through your normal package-management process. Do not substitute a similarly named script from an untrusted directory.

2. Understand the destination name

dpkg-name reads the package control data and constructs a name in this shape:

package_version_architecture.package-type

The version combines the upstream version and, when present, the Debian revision. The package type comes from the package metadata; if that field is absent, the command falls back to deb. This is metadata-driven, so the input filename is not a trustworthy description of the package inside it.

For example, a file called download.deb might become widget_1.4-2_amd64.deb. The exact result depends on the package's control data and the architecture selected by the installed tool. Do not write a script that assumes a particular version or architecture unless you have already inspected the package.

3. Rename one package in place

Start with one file and a directory listing. Replace the placeholder with an actual path:

$ cd /path/to/package-directory
$ ls -l -- package-download.deb
$ dpkg-name -- package-download.deb
$ ls -l --

The file is moved to the full destination name in the same directory. A successful run normally produces no explanatory output, so the second listing is the checkpoint. Use find or ls to confirm the old name is gone and the new .deb name is present.

The -- separates options from filenames. Keep it when a path might begin with a hyphen. Quote paths containing whitespace or shell characters:

$ dpkg-name -- "/path/to/package directory/package-download.deb"

This operation changes the directory entry, not the package contents. Recovery is straightforward if you recorded the old name: rename the result back with mv -- full-name.deb package-download.deb. Do not use that undo command until you have substituted the exact names from your listing.

4. Keep or remove the architecture field

Use --no-architecture, or its short form -a, when the destination should omit the architecture:

$ dpkg-name --no-architecture -- package-download.deb
$ ls -1 -- *.deb
widget_1.4-2.deb

Without this option, the normal full name includes the architecture, for example widget_1.4-2_amd64.deb. The shorter form is convenient interactively, but the long form is easier to review in a maintenance script.

Do not infer that removing the architecture changes package compatibility. It changes the filename only. Keep the architecture in names used by repositories or automation unless the consumer explicitly expects architecture-free names.

5. Use symlinks when you need a second name

The default action moves the file. If another tool needs the canonical name while an existing path must remain, use --symlink, or -k:

$ dpkg-name --symlink -- package-download.deb
$ ls -l -- package-download.deb widget_1.4-2_amd64.deb
lrwxrwxrwx ... package-download.deb -> widget_1.4-2_amd64.deb
-rw-r--r-- ... widget_1.4-2_amd64.deb

The exact permissions, timestamps and architecture vary. The useful check is that the old path is a symbolic link and the target is the package file. Removing the link does not remove the target, but deleting the target makes the link unusable. Treat symlinks carefully when handing archives to tools that copy or publish files.

6. Treat overwrite and subdirectories as deliberate changes

By default, an existing destination is not something to overwrite casually. --overwrite, or -o, explicitly permits an existing file with the same destination name to be replaced. This is destructive: make a backup or use a separate staging directory first.

$ cp --preserve=all -- widget_1.4-2_amd64.deb widget_1.4-2_amd64.deb.bak
$ dpkg-name --overwrite -- package-download.deb
$ dpkg-deb --info -- widget_1.4-2_amd64.deb | head

Keep the backup until the replacement has been checked. If it is wrong, restore it with mv -- widget_1.4-2_amd64.deb.bak widget_1.4-2_amd64.deb. Removing the backup is irreversible, so make that a separate, reviewed action.

--subdir, or -s, moves files into a subdirectory. Supplying an existing directory is the least surprising form:

$ mkdir -p -- renamed
$ dpkg-name --subdir renamed -- package-download.deb
$ ls -l -- renamed/

Without a directory argument, dpkg-name derives a hierarchy from the package section, architecture and distribution layout. The manual warns that this can become messy, especially when section metadata is missing. Avoid the derived layout unless you have a clear reason and have tested it on a copy.

--create-dir, or -c, creates a missing target directory when used with --subdir. It changes the filesystem, so inspect the destination and use it only in a staging area. There is no single undo command for a batch: record the moved paths, then move each package back before removing any directory you created.

7. Avoid unsafe bulk renaming

A recursive pipeline can rename more files than intended, and --overwrite can destroy existing archives. The manual specifically warns against combining a broad find search with overwrite, subdirectories and directory creation: packages often lack section metadata, so the resulting archive layout can be unusable.

If a batch is necessary, work in a copy or staging directory, select files deliberately, and test one package first:

$ find /path/to/staging -maxdepth 1 -type f -name '*.deb' -print
$ dpkg-name -- /path/to/staging/one-package.deb
$ find /path/to/staging -maxdepth 1 -type f -name '*.deb' -print

Only after the before-and-after lists make sense should you consider processing more files. Keep package contents unchanged, preserve the original archive directory until verification is complete, and do not run the command as root merely to avoid a permissions error.