Skip to main content

Switching Debian apt to the Aliyun Mirror

· 5 min read
tanzhuo

A fresh Debian install uses the official sources by default, and from inside China package downloads often crawl along at a few dozen KB/s — installing anything means staring at a stalled progress bar. Switching the apt sources to Aliyun's domestic mirror is usually the first thing I do on a new machine, so here are the steps and the things to watch out for.

Why switch mirrors​

When apt installs software, it downloads packages and indexes from the repository URLs configured in /etc/apt/sources.list. The official servers are overseas, so access from China means high latency and low bandwidth — apt-get update and apt-get install are slow and sometimes time out entirely. Mirror sites like Aliyun, Tsinghua, and USTC regularly sync the complete repository from the official source. The package contents are identical; only the address changes to a domestic node, and the speedup is an order of magnitude.

Anatomy of a source entry​

Before touching anything, it helps to understand what each line in sources.list means. The format is fixed:

deb [repository URL] [release codename] [components...]
  • deb denotes a binary package repository; deb-src is the corresponding source repository. If you only install software, you can skip the deb-src lines.
  • The release codename maps to the Debian version — stretch, for example, is Debian 9. The codename must match your system's version; you can confirm with cat /etc/os-release.
  • Among the components, main is the official main repository, while contrib and non-free contain packages that depend on or are themselves non-free software, such as certain drivers and firmware — usually worth including.
  • stretch/updates is the security update repository, stretch-updates carries regular updates, and stretch-backports provides packages backported from newer releases.

Steps​

1）Open the source list file

vim /etc/apt/sources.list

Back it up first so you can restore it if anything goes wrong:

# Back up the existing source configuration
cp /etc/apt/sources.list /etc/apt/sources.list.bak

# Edit the source list
vim /etc/apt/sources.list

2）Add the Aliyun mirror URLs

Comment out or clear the existing content and add the following lines (using stretch, i.e. Debian 9, as an example):

deb http://mirrors.aliyun.com/debian/ stretch main non-free contrib
deb-src http://mirrors.aliyun.com/debian/ stretch main non-free contrib
deb http://mirrors.aliyun.com/debian-security stretch/updates main
deb-src http://mirrors.aliyun.com/debian-security stretch/updates main
deb http://mirrors.aliyun.com/debian/ stretch-updates main non-free contrib
deb-src http://mirrors.aliyun.com/debian/ stretch-updates main non-free contrib
deb http://mirrors.aliyun.com/debian/ stretch-backports main non-free contrib
deb-src http://mirrors.aliyun.com/debian/ stretch-backports main non-free contrib

Plain-text version for easy copying:

deb http://mirrors.aliyun.com/debian/ stretch main non-free contrib
deb-src http://mirrors.aliyun.com/debian/ stretch main non-free contrib
deb http://mirrors.aliyun.com/debian-security stretch/updates main
deb-src http://mirrors.aliyun.com/debian-security stretch/updates main
deb http://mirrors.aliyun.com/debian/ stretch-updates main non-free contrib
deb-src http://mirrors.aliyun.com/debian/ stretch-updates main non-free contrib
deb http://mirrors.aliyun.com/debian/ stretch-backports main non-free contrib
deb-src http://mirrors.aliyun.com/debian/ stretch-backports main non-free contrib

3）Refresh the sources

Save and exit, then refresh the local package index so the new configuration takes effect:

apt-get update

This step re-fetches all repository index files from the Aliyun mirror; you should see mirrors.aliyun.com addresses in the output. From then on, apt-get install downloads go through the domestic mirror.

Pitfalls and notes​

  • The codename must match your system version. Point the stretch sources at a different release and, at best, update throws 404s; at worst, you mix packages from different releases and wreck your dependencies. For other versions, just replace every stretch above with the corresponding codename.
  • On newer Debian releases, the security source format changed from codename/updates to codename-security. Copying from old articles will get you a repository-not-found error — trust the configuration shown on the mirror site's homepage.
  • If update fails with GPG signature errors, it's usually a missing key or a wrong system clock. Check the clock first, then the keys — don't force the install by skipping verification.
  • On internal networks or environments where stability matters, after switching sources run apt-get update and install a small package as a sanity check before doing any large-scale installs or upgrades.

Wrapping up​

Switching mirrors is really just three steps: back up and edit /etc/apt/sources.list, add the mirror URLs, and refresh the index with apt-get update. The key is making sure the codename matches your system version, and keeping a backup so you can roll back at any time. The same approach works for the Tsinghua and USTC mirrors — just a different domain name.

COMMENTS