apt Operations

The apt module manages packages and repositories on Debian-based systems using the apt package manager.

Functions

packages

Install, remove, or update apt packages.

from pyinfra.operations import apt

apt.packages(
    name="Install web server",
    packages=["nginx", "certbot"],
    update=True,
)

str | list[str]

List of packages to ensure. Can be a single package name or a list of package names.

bool

default:true

Whether the packages should be installed.

bool

default:false

Whether to upgrade packages without a specified version.

bool

default:false

Run apt update before installing packages.

int

When used with update, cache package index for this many seconds.

bool

default:false

Run apt upgrade before installing packages.

bool

default:false

Force package installs by passing --force-yes to apt.

bool

default:false

Don’t install recommended packages.

bool

default:false

Allow downgrading packages with version (—allow-downgrades).

str

Additional arguments to the apt install command.

str

Additional arguments to the apt uninstall command.

Package versions can be pinned like apt: <pkg>=<version>

Examples

from pyinfra.operations import apt

# Update package list and install packages
apt.packages(
    name="Install Asterisk and Vim",
    packages=["asterisk", "vim"],
    update=True,
)

from pyinfra import host
from pyinfra.operations import apt
from pyinfra.facts.server import OsVersion

# Install kernel headers matching current kernel
apt.packages(
    name="Install kernel headers",
    packages=[f"linux-headers-{host.get_fact(OsVersion)}"],
    update=True,
)

from pyinfra.operations import apt

# Install the latest versions of packages (always check)
apt.packages(
    name="Install latest Vim",
    packages=["vim"],
    latest=True,
)

from pyinfra.operations import apt

# Install without recommended packages
apt.packages(
    name="Install minimal nginx",
    packages=["nginx"],
    no_recommends=True,
)

update

Update apt package indexes.

from pyinfra.operations import apt

apt.update(
    name="Update apt repositories",
    cache_time=3600,
)

int

Cache updates for this many seconds. When set, the /var/lib/apt/periodic/update-success-stamp file is touched upon successful update.

This operation is not idempotent by default unless cache_time is specified.

upgrade

Upgrade all apt packages.

from pyinfra.operations import apt

apt.upgrade(
    name="Upgrade all packages",
    auto_remove=True,
)

bool

default:false

Remove transitive dependencies that are no longer needed.

dist_upgrade

Upgrade all apt packages using dist-upgrade.

from pyinfra.operations import apt

apt.dist_upgrade(
    name="Upgrade apt packages using dist-upgrade",
    auto_remove=True,
)

bool

default:false

Remove transitive dependencies that are no longer needed.

repo

Add or remove apt repositories.

from pyinfra.operations import apt

apt.repo(
    name="Install VirtualBox repo",
    src="deb https://download.virtualbox.org/virtualbox/debian bionic contrib",
)

str

required

Apt source string, e.g., deb http://example.com hardy main

bool

default:true

Whether the repo should exist on the system.

str

Optional filename to use /etc/apt/sources.list.d/<filename>.list. By default uses /etc/apt/sources.list.

ppa

Add or remove Ubuntu PPA repositories.

from pyinfra.operations import apt

apt.ppa(
    name="Add the Bitcoin ppa",
    src="ppa:bitcoin/bitcoin",
)

str

required

The PPA name in full ppa:user/repo format.

bool

default:true

Whether it should exist.

Requires apt-add-repository (from software-properties-common) on the remote host.

This operation is not idempotent.

deb

Install or remove .deb package files.

from pyinfra.operations import apt

apt.deb(
    name="Install Chrome via deb",
    src="https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb",
)

str

required

Filename or URL of the .deb file.

bool

default:true

Whether the package should exist on the system.

bool

default:false

Force package install by passing --force-yes to apt.

When installing, apt-get install -f will be run to install any unmet dependencies.

URL sources with present=False: If the .deb file isn’t downloaded, pyinfra can’t remove any existing package as the file won’t exist until mid-deploy.

key

Add apt GPG keys.

from pyinfra.operations import apt

apt.key(
    name="Add the Docker apt gpg key",
    src="https://download.docker.com/linux/ubuntu/gpg",
)

str

Filename or URL of the key file.

str

URL of keyserver to fetch key from.

str | list[str]

Key ID or list of key IDs when using keyserver.

keyserver and keyid must be provided together.

apt-key is deprecated in Debian. It is recommended NOT to use this operation. Instead, follow the instructions at: https://wiki.debian.org/DebianRepository/UseThirdParty

Examples

from pyinfra.operations import apt

apt.key(
    name="Add the Docker apt gpg key",
    src="https://download.docker.com/linux/ubuntu/gpg",
)

from pyinfra.operations import apt

apt.key(
    name="Add VirtualBox key from keyserver",
    keyserver="keyserver.ubuntu.com",
    keyid="A2F683C52980AECF",
)

Common Use Cases

Full System Update

from pyinfra.operations import apt

# Update package list
apt.update(
    name="Update package list",
    cache_time=3600,
)

# Upgrade all packages
apt.upgrade(
    name="Upgrade all packages",
    auto_remove=True,
)

Install from Third-Party Repository

from pyinfra.operations import apt

# Add repository key
apt.key(
    name="Add Docker GPG key",
    src="https://download.docker.com/linux/ubuntu/gpg",
)

# Add repository
apt.repo(
    name="Add Docker repository",
    src="deb https://download.docker.com/linux/ubuntu focal stable",
    filename="docker",
)

# Update and install
apt.packages(
    name="Install Docker",
    packages=["docker-ce", "docker-ce-cli", "containerd.io"],
    update=True,
)

Development Environment Setup

from pyinfra.operations import apt

apt.packages(
    name="Install development tools",
    packages=[
        "build-essential",
        "git",
        "vim",
        "tmux",
        "curl",
        "wget",
    ],
    update=True,
    cache_time=3600,
)

Overview

Package Managers

Language Packages

Service Management

System Operations

Containers

Databases

Version Control

Security

Functions

packages

Examples

update

upgrade

dist_upgrade

repo

ppa

deb

key

Examples

Common Use Cases

Full System Update

Install from Third-Party Repository

Development Environment Setup

​Functions

​packages

​Examples

​update

​upgrade

​dist_upgrade

​repo

​ppa

​deb

​key

​Examples

​Common Use Cases

​Full System Update

​Install from Third-Party Repository

​Development Environment Setup

Functions

packages

Examples

update

upgrade

dist_upgrade

repo

ppa

deb

key

Examples

Common Use Cases

Full System Update

Install from Third-Party Repository

Development Environment Setup