Repositories: Difference between revisions

From Alpine Linux
No edit summary
(Style/grammar amendments; repos standardized to italics, as per majority use on this page, but preserving boldface in introductory instances.)
 
(39 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{TOC right}}
{{TOC right}}


== Repositories ==
A [https://en.wikipedia.org/wiki/Software_repository repository] is a storage location with a collection of Alpine Linux [[Alpine Package Keeper#Packages and Repositories|packages]]. In addition to the three [[#Official repositories|official repositories]], technically, any directory with a collection of {{ic|*.apk}} files with a special index file named {{Path|APKINDEX.tar.gz}} can be considered a repository, albeit a personal repository. [[Alpine Package Keeper|Alpine Package Keeper ('''apk''')]] loads repository definitions from {{Path|/etc/apk/repositories}}, has sub-commands to query repositories, and maintains the desired system state as per [[Alpine_Package_Keeper#World|world]].


There are three package repositories in Alpine Linux:
== Official repositories ==
 
There are three official package repositories available in Alpine Linux: [[#Main|main]], [[#Community|community]] and [[#Testing|testing]]. These repositories directly correspond to three directories of [[Aports tree|aports]].


=== Main ===
=== Main ===


Packages in '''main''' repository are the software that have direct support and updates from the Alpine core team. Alpine Linux tries to limit the amount of packages in ''main'' to only include base system packages, i.e packages which are needed by other packages or are needed to setup a basic system. Packages in ''main'' must '''not''' have dependencies in other repositories.
Packages in the '''main''' repository are the software that has direct support and updates from the Alpine core team. Alpine Linux tries to limit the amount of packages in ''main'' to only include essential base system packages i.e. those that are required to set up a minimal functional system, along with those packages' dependencies.
 
Packages in '''main''' repository also have official special documentation, are always available for all releases and will have substitutions if some are not continued from upstream. Commonly these packages are selected due to their responsibility and stability with respect to upstream availability. Packages from ''community'' or (rarely) ''testing'' can be accepted into the ''main'' repository.


=== Community ===
=== Community ===


Packages in '''community''' repository are those made by users in team with the official developers and close to the Alpine package process. They are supported by those user(s) contributions and could end if the user(s) stops; they may also be removed in a future release due to lack of support by upstream authors.  
Packages in the '''community''' repository are those made by users in team with the official developers and are close to the Alpine Linux packaging process. They are supported by those user(s) contributions, and support ends [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html#_repositories_releases_and_mirrors six months after their release]. They may also be removed in a future release due to lack of support by upstream authors or, rarely, if the user contribution(s) stop(s).  


The '''community''' repository was introduced with Alpine Linux version [https://alpinelinux.org/posts/Alpine-3.3.0-released.html 3.3.0]. Packages from ''testing'' that are accepted go to the ''community'' repository.
If packages from the ''community'' repository are used, one would need to upgrade that repo [[Upgrading_Alpine#Upgrading_to_latest_release|to the latest stable release branch]] to continue to have support.


=== Testing ===
=== Testing ===


The ''testing'' repository is only available on [[#Edge|edge]] branch i.e development branch and this is where new packages go. These are made by any contributor to Alpine. .  Packages from ''testing'' that are accepted go to the ''community'' repository or (rarely) the ''main'' repository. Packages in ''testing'' have no support (staging only) and only built for ''edge''. If it stays here long enough it gets moved to unmaintained/purged (gets cleaned up every 6 months).
The '''testing''' repository is only available on the [[#Edge|edge]] branch, i.e. the development branch, and this is where new packages go. These are made by any contributor to Alpine Linux. Packages from ''testing'' that are accepted go to the ''community'' repository or (more rarely) to the ''main'' repository. Packages in ''testing'' have no support (staging only) and are built only for the [[#Edge|edge]] branch.


Before a package can move from ''testing'' to ''main'' or ''community'', the following requirements must be met:
== Release Branches ==


# Package must work correctly, including the init.d script (if provided) and default configuration.
Each stable release branch of Alpine Linux has its own ''main'' and ''community'' repositories. The [https://alpinelinux.org/releases/ releases] page has information on all the release branches along with support status. Support entails security patches for the given feature versions.  
# Packaging must be done correctly, with files installed in the right places, e.g. configs are in <code>/etc/</code> and not in <code>/usr/etc</code>.
# Package dependencies are handled correctly. Abuild can (and should) autodetect shared libs, for example ''sqlite-libs'' provides ''so:libsqlite3.so.0''. Any package linked to ''sqlite'' should have an automatically (by abuild) added <code>depend=so:libsqlite3.so.0</code> and the user should not have to manually add a <code>depend="sqlite-libs"</code> in the APKBUILD.
# There is a maintainer who claims responsibility for the maintenance of the package and can help fix things if they break in the future.


== Managing repositories ==
'''The current stable release branch of Alpine Linux is {{#expr:{{AlpineLatest}}}}'''.


The package repositories that <code>apk</code> uses to retrieve package files for installation are specified in file {{path|/etc/apk/repositories}}. Each line of this file specifies the location of a package repository, and optionally a tag. Lines that start with a hash character (#) are ignored.
== Edge ==


The location may be an <code>http://</code> or <code>https://</code> URL, or the path to a directory on the local filesystem. A [[Package_management#Repository_pinning|tagged]] repository is prefixed with the <code>@tag</code> specifier, followed by a space and the repository location.
'''Edge''' is the name given to the current [[Aports tree|development tree]] of Alpine Linux. The ''edge'' branch includes all three [[#Official repositories|official repositories]] and contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis. Since ''edge'' is a development branch, many changes are not heavily tested (or tested at all), and packages can and sometimes do break without warning. ''edge'' can be considered as the '''rolling release version''' of Alpine Linux.


The default will look something like:
[[#Upgrading to edge|Upgrading to the ''edge'']] branch and installing packages from [[Repositories#Testing|''testing'']] repository, and then submitting '''[https://gitlab.alpinelinux.org/alpine/aports/issues bug reports]''' is one of the best ways to [[Contribute|contribute]] to Alpine Linux. This is a very valuable activity that helps Alpine Linux development, as it ensures that the quality of stable releases is high.


{{cat|/etc/apk/repositories|#/media/cdrom/apks
The currently installed ''edge'' version – i.e the build date that is attached to the ''edge'' release – may be checked with the command:{{Cmd|$ cat /etc/alpine-release}}
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
{{Warning|Do not use the [[#Edge|''edge'' branch]] in production nor if you desire deterministic, repeatable package installation (such as with containerized environments) via [[Alpine Package Keeper#Package pinning|package pinning]], as it is under constant development.  Instead, use a [[#Release Branches|stable release branch]].}}
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community}}


To automatically configure {{path|/etc/apk/repositories}}, use:
=== Message on /usr merge ===
{{cmd|# [[Alpine setup scripts#setup-apkrepos|setup-apkrepos]] -cf}}


After making changes to {{path|/etc/apk/repositories}} you should update the package index using:
''Edge'' currently issues a message encouraging users to install the {{pkg|merge-usr}} package that would update the base filesystem hierarchy. Consult the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html news release on /usr merge] for background information, including its rationale.
{{cmd|# apk update}}


{{Note| For better security you should probably change the url's from '''http''' to '''https'''. Some Alpine Linux package mirrors may not support '''https'''. If that is the case, you will need to change mirrors or revert back. You can check if your mirror supports '''https''' on https://mirrors.alpinelinux.org }}
This is currently not a requirement but will be implemented in the future as part of standard system upgrade to a [[Upgrading_Alpine#Upgrading_to_latest_release|new release]], as mentioned in gitlab issue {{Issue|17624}}. You can disable this nag message by [[Alpine_Package_Keeper#Package_masking|masking]] the {{Pkg|usr-merge-nag}} package: {{Cmd|$ doas apk add '!usr-merge-nag'}}


== Release Branches ==
{{Warning|If any error is reported upon trying a dry run by using {{ic|$ doas merge-usr --dryrun}}, do not proceed with the ''/usr merge'', as this would break your system. Instead, it would be appreciated if you could kindly submit a '''[https://gitlab.alpinelinux.org/alpine/aports/issues bug report]''' and provide all requested information when doing so.}}


There are several release branches for Alpine Linux available at the same time. Each May and November we make a release branch from ''edge''. '''The current release branch of Alpine Linux is {{#expr:{{AlpineLatest}}}}'''.
== Managing repositories ==


The '''main''' repository of every release branch is typically supported for 2 years. The '''community''' repository of any release branch is supported until next stable release i.e six months. Security fixes beyond that can be made on request when there are patches available.  
The package repositories that '''apk''' uses to retrieve package files for installation are specified in the {{path|/etc/apk/repositories}} file. Each line in {{path|/etc/apk/repositories}} specifies the location of a package repository, one repository per line, and optionally with a [[#Tagged_repository|tag]]. Lines that start with a hash character (#) are there for comments or to disable a "repo" line (temporarily or not) and are ignored by '''apk'''.


{{Note|If packages from community repository are used, one needs to update to the latest release branch to continue to have support.}}
The location may be an <code>http://</code> or <code>https://</code> URL, or the path to a directory on the local filesystem. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), then your repository file probably looks something like this: {{Cat|/etc/apk/repositories|/media/sda1/apks/}}


'''To upgrade''' to the latest release branch, follow the steps in  [[Upgrading_Alpine#Upgrading_to_latest_release|Upgrading Alpine Linux]].
{{Tip|During [[installation]], only the [[#Main|''main'']] repository is enabled, so [[#Enabling the community repository|enable the ''community'' repository]] if required, as follows.}}


== Edge==
=== Enabling the community repository ===


''edge'' is the name given to the current [[Aports tree|development tree]] of Alpine Linux.  ''edge'' can be considered as '''rolling release version''' of Alpine Linux. This version contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis.
The [[Alpine setup scripts#setup-apkrepos|setup-apkrepos]] script can be used to enable the [[#Community|''community'']] repository, as follows: {{cmd|# setup-apkrepos -c}}


<br>
With the above change, the {{path|/etc/apk/repositories}} file will look something like: {{cat|/etc/apk/repositories|#/media/cdrom/apks
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community}}


{{Warning|''edge'' is under constant development so be careful using it in production. It is possible that bugs in ''edge'' could cause data loss or could break your system.}}
{{Note|For better security, you should probably change the urls from '''http''' to '''https'''. Some Alpine Linux package mirrors may not support '''https'''. If that is the case, you will need to change mirrors or revert back. You can check whether your mirror supports '''https''' on the [https://mirrors.alpinelinux.org official mirrors listing].}}


Since ''edge'' is a development branch, many changes are not heavily tested (or tested at all) and packages in ''edge'' can and sometimes do break without warning. However, testing ''edge'' is a very valuable activity which helps the Alpine Linux development to ensure that the quality of the stable releases is high. Testing ''edge'' is a great way to contribute to the Alpine Linux development.
=== Tagged repository ===


Similar to [[#Release Branches|release branches]] edge consists of '''main''' and '''community'''  repositories in addition to the third repository i.e '''testing'''.
A tagged repository is prefixed with the <code>@tag</code> specifier, followed by a space and the repository location in the {{Path|/etc/apk/repositories}} file, as follows.{{Cat|/etc/apk/repositories|https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
@personal https:/personal-repo.example.com/alpine-apks/}}


The optional <code>@tag</code> specifier, when used as shown above (<code>@personal</code>), indicates that the tagged repository should not be used by default: [[apk]] will by default only use the untagged repositories, but adding a package from an <code>@</code>-tagged repository will make '''apk''' prefer the tagged repository for the named package, even if a later version of the ''same package'' is available in another repository. It allows pulling in dependencies for the tagged package from the tagged repository, though it ''prefers to use untagged repositories to satisfy dependencies'' when possible.


For example, {{ic|apk add busybox@personal}} enables the selection of {{ic|busybox}} from a tagged repository named <code>@personal</code>. That command enables the installation of {{ic|busybox}} and its dependencies from the <code>@personal</code> tagged repository.  Since tagged repositories are ''not'' prioritized, if a version of {{ic|busybox}}'s ''dependency'' from an untagged repository is a better fit, it will be used.


=== Upgrading to edge ===
=== Upgrading to edge ===


{{:Include:Upgrading to Edge}}
Follow the instructions for [[Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge|Upgrading to Edge]].
 
=== Using testing repository in release branches ===


Installing packages from '''testing''' repository of '''edge''' branch with '''main''' or '''community''' repositories in the '''release branch''' usually will not work.
When using edge branch, the [[Repositories#Testing|''testing'']] repository can be added as a [[Repositories#Tagged repository|tagged repository]]. Remember that packages in [[Repositories#Testing|''testing'']] repository have no support.


{{Warning|'''Only do this if you're 100% sure what you're doing!''' Alpine does not officially support mixing branches this way.}}
{{Warning|Do not enable ''main''/''community'' repositories from both the [[Repositories#Release Branches|'''stable''' release branch]] and from [[Repositories#Edge|'''edge''']] at the same time. This can break your system. Either use edge '''or''' stable. If you mix stable and edge repositories, you're on your own.}}


Edit the file {{path|/etc/apk/repositories}} and add (or uncomment) a line that points to the "testing" directory, while also [[Package_management#Repository_pinning|tagging]] the repository, for example:
=== Using testing repository ===


{{Cat|/etc/apk/repositories|
Unlike [[#Edge|edge]] branch, installing packages from ''testing'' repository in a '''stable''' [[#Release Branches|release branch]] is not recommended and is not guaranteed to work. However, if you need a package that is only available in the [[#Testing|''testing'']] repository, add the ''testing'' repository as a [[#Tagged repository|tagged repository]] by editing the {{path|/etc/apk/repositories}} file as follows:{{Cat|/etc/apk/repositories|https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing
@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing}}
}}


In that case, the tag is <code>@testing</code>, which allows you to pull packages from that repository without potentially messing up your install (too badly):
Before installing a package from the ''testing'' repository, [[Alpine_Package_Keeper#Check_Dependencies|check for dependencies]]. Installing a package from ''testing'' repository that depends on libraries in ''main'' or ''community'' often won't work due to a potential version mismatch. Alpine Linux does not officially support mixing branches this way, as mixing packages from stable and edge releases can break your system.


{{cmd|# apk add wireguard-go@testing}}
For example, with the command {{ic|# apk add wireguard-go@testing}}, the <code>@testing</code> tag allows [[apk]] to pull the necessary package(s) from the ''testing'' repository without potentially messing up your installation (too badly).


= See also =
== See also ==


* [[Alpine_Package_Keeper|Alpine Package Keeper]]
* [[Alpine_Package_Keeper#World| The Alpine Linux world file]]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-repositories.5.scd Manual for apk-repositories(5)]
* [[Alpine Linux in a chroot]]
* [[Alpine Linux in a chroot]]
* [https://bugs.alpinelinux.org/ Report Bugs]
* [https://bugs.alpinelinux.org/ Report Bugs]

Latest revision as of 23:57, 3 February 2026

A repository is a storage location with a collection of Alpine Linux packages. In addition to the three official repositories, technically, any directory with a collection of *.apk files with a special index file named APKINDEX.tar.gz can be considered a repository, albeit a personal repository. Alpine Package Keeper (apk) loads repository definitions from /etc/apk/repositories, has sub-commands to query repositories, and maintains the desired system state as per world.

Official repositories

There are three official package repositories available in Alpine Linux: main, community and testing. These repositories directly correspond to three directories of aports.

Main

Packages in the main repository are the software that has direct support and updates from the Alpine core team. Alpine Linux tries to limit the amount of packages in main to only include essential base system packages i.e. those that are required to set up a minimal functional system, along with those packages' dependencies.

Community

Packages in the community repository are those made by users in team with the official developers and are close to the Alpine Linux packaging process. They are supported by those user(s) contributions, and support ends six months after their release. They may also be removed in a future release due to lack of support by upstream authors or, rarely, if the user contribution(s) stop(s).

If packages from the community repository are used, one would need to upgrade that repo to the latest stable release branch to continue to have support.

Testing

The testing repository is only available on the edge branch, i.e. the development branch, and this is where new packages go. These are made by any contributor to Alpine Linux. Packages from testing that are accepted go to the community repository or (more rarely) to the main repository. Packages in testing have no support (staging only) and are built only for the edge branch.

Release Branches

Each stable release branch of Alpine Linux has its own main and community repositories. The releases page has information on all the release branches along with support status. Support entails security patches for the given feature versions.

The current stable release branch of Alpine Linux is 3.23.

Edge

Edge is the name given to the current development tree of Alpine Linux. The edge branch includes all three official repositories and contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis. Since edge is a development branch, many changes are not heavily tested (or tested at all), and packages can and sometimes do break without warning. edge can be considered as the rolling release version of Alpine Linux.

Upgrading to the edge branch and installing packages from testing repository, and then submitting bug reports is one of the best ways to contribute to Alpine Linux. This is a very valuable activity that helps Alpine Linux development, as it ensures that the quality of stable releases is high.

The currently installed edge version – i.e the build date that is attached to the edge release – may be checked with the command:

$ cat /etc/alpine-release

Warning: Do not use the edge branch in production nor if you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, as it is under constant development. Instead, use a stable release branch.


Message on /usr merge

Edge currently issues a message encouraging users to install the merge-usr package that would update the base filesystem hierarchy. Consult the news release on /usr merge for background information, including its rationale.

This is currently not a requirement but will be implemented in the future as part of standard system upgrade to a new release, as mentioned in gitlab issue #17624. You can disable this nag message by masking the usr-merge-nag package:

$ doas apk add '!usr-merge-nag'

Warning: If any error is reported upon trying a dry run by using $ doas merge-usr --dryrun, do not proceed with the /usr merge, as this would break your system. Instead, it would be appreciated if you could kindly submit a bug report and provide all requested information when doing so.


Managing repositories

The package repositories that apk uses to retrieve package files for installation are specified in the /etc/apk/repositories file. Each line in /etc/apk/repositories specifies the location of a package repository, one repository per line, and optionally with a tag. Lines that start with a hash character (#) are there for comments or to disable a "repo" line (temporarily or not) and are ignored by apk.

The location may be an http:// or https:// URL, or the path to a directory on the local filesystem. If you booted from a USB stick (/media/sda1) or CD-ROM (/media/cdrom), then your repository file probably looks something like this:

Contents of /etc/apk/repositories

/media/sda1/apks/
Tip: During installation, only the main repository is enabled, so enable the community repository if required, as follows.

Enabling the community repository

The setup-apkrepos script can be used to enable the community repository, as follows:

# setup-apkrepos -c

With the above change, the /etc/apk/repositories file will look something like:

Contents of /etc/apk/repositories

#/media/cdrom/apks http://dl-cdn.alpinelinux.org/alpine/v3.23/main http://dl-cdn.alpinelinux.org/alpine/v3.23/community
Note: For better security, you should probably change the urls from http to https. Some Alpine Linux package mirrors may not support https. If that is the case, you will need to change mirrors or revert back. You can check whether your mirror supports https on the official mirrors listing.

Tagged repository

A tagged repository is prefixed with the @tag specifier, followed by a space and the repository location in the /etc/apk/repositories file, as follows.

Contents of /etc/apk/repositories

https://dl-cdn.alpinelinux.org/alpine/v3.23/main https://dl-cdn.alpinelinux.org/alpine/v3.23/community @personal https:/personal-repo.example.com/alpine-apks/

The optional @tag specifier, when used as shown above (@personal), indicates that the tagged repository should not be used by default: apk will by default only use the untagged repositories, but adding a package from an @-tagged repository will make apk prefer the tagged repository for the named package, even if a later version of the same package is available in another repository. It allows pulling in dependencies for the tagged package from the tagged repository, though it prefers to use untagged repositories to satisfy dependencies when possible.

For example, apk add busybox@personal enables the selection of busybox from a tagged repository named @personal. That command enables the installation of busybox and its dependencies from the @personal tagged repository. Since tagged repositories are not prioritized, if a version of busybox's dependency from an untagged repository is a better fit, it will be used.

Upgrading to edge

Follow the instructions for Upgrading to Edge.

When using edge branch, the testing repository can be added as a tagged repository. Remember that packages in testing repository have no support.

Warning: Do not enable main/community repositories from both the stable release branch and from edge at the same time. This can break your system. Either use edge or stable. If you mix stable and edge repositories, you're on your own.


Using testing repository

Unlike edge branch, installing packages from testing repository in a stable release branch is not recommended and is not guaranteed to work. However, if you need a package that is only available in the testing repository, add the testing repository as a tagged repository by editing the /etc/apk/repositories file as follows:

Contents of /etc/apk/repositories

https://dl-cdn.alpinelinux.org/alpine/v3.23/main https://dl-cdn.alpinelinux.org/alpine/v3.23/community @testing https://dl-cdn.alpinelinux.org/alpine/edge/testing

Before installing a package from the testing repository, check for dependencies. Installing a package from testing repository that depends on libraries in main or community often won't work due to a potential version mismatch. Alpine Linux does not officially support mixing branches this way, as mixing packages from stable and edge releases can break your system.

For example, with the command # apk add wireguard-go@testing, the @testing tag allows apk to pull the necessary package(s) from the testing repository without potentially messing up your installation (too badly).

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Repositories&oldid=32009"