# &app; Manual V&manrevision;

2003,2004
Sebastian Heinlein
Sebastian
Heinlein
This manual describes version &appversion; of Synaptic Package Manager.

## Legal Notice

This document is distributed under the terms of the GNU Public license as published by the Free Software; either version 2 of the License, or (at your option) later version. A copy of this license can be found in , or in the file included with the source code of this program.

## Feedback

To report a bug or make a suggestion regarding the &app; or this manual, use the bug report system at Synaptic Web, contact the mailing list synaptic-devel@nongnu.org join the IRC channel #synaptic on irc.freenode.org.

## Introduction

The &app; enables you to install software onto your computer and to manage the software, that is already installed. The software is bundled in so called packages. A single application can even exist of several packages: e.g. the Mozilla Internet Suite is packaged to mozilla-browser, that contains the actual browser, and mozilla-mail , that contains the mail client (this example refers to Debian GNU/Linux and can be different on your distribution).

Nearly all applications reuse the functionality of other applications or libraries (libraries only provide functions to other libraries or applications and are no stand alone applications) to avoid doubled efforts. So the most packages depend on other packages. The &app; resolves the dependencies for you automatically.

Technically the &app; is based on the package manager APT and provides functions, that are similar to the ones of the command line tool `apt-get` in a graphical environment.

In detail &app; provides the following features:

- Install, remove, configure, upgrade and downgrade single and multiple packages.

- Upgrade your whole system.

- Manage package repositories.

- Search packages by name, description and several other attributes.

- Select packages by status, section, name or a custom filter.

- Sort packages by name, status, size or version.

- Browse all available online documentation related to a package.

- Lock packages to the current version.

- Force the installation of a specific package version.

You need root rights to install or remove software packages on your computer.

You can start &app; in the following ways:

Cinnamon menu

  Choose Administration Synaptic Package Manager .

GNOME 3 select Activities

  Choose Show Applications All Synaptic Package Manager .

GNOME 2 Applications menu

  Choose System Tools Synaptic Package Manager .

KDE menu

  Choose Settings Extra Synaptic Package Manager .

Mate Applications menu

  Choose System Tools Synaptic Package Manager .

Command line

  To start &app; from a command line type the following , then press Return:

  `synaptic`

You can render your system unusable.

Synaptic allows you to perform changes on the core of your system.

Always use &app; with care.

## Main Window

### Overview

When you start &app;, the following window is displayed.

#### &app; Start Up Window

Shows &app; main window. Contains titlebar, menubar, toolbar, display area, and scrollbars. Menubar contains File, View, Settings, and Help menus.

#### &app; Window Components

Component | Description
--- | ---
Menubar | Contains menus that you can use to perform actions in &app;.
Toolbar | Provides main actions.
Category selector | Provides categories to narrow down the list of shown listed packages.
Package list | Lists known packages. The list can be narrowed down by using filters and categories.
Description field | Shows the description of the selected package.
Statusbar | Displays global informations about the status of &app;.

### Toolbar

#### &app; toolbar

Shows the toolbar of the &app; main window

The toolbar provides the following actions:

Reload

  Reload the list of known packages.

Mark all Upgrades

  Mark all possible and available upgrades.

Apply

  Apply all marked changes.

Properties

  Open the dialog of the selected package.

Search

  Open the package search dialog.

### Category Selector

The selector on the left side allows you to narrow down the packages, that are shown in the by categories.

#### Category Selector

Shows the category selector in the &app; main window.

The following categories are available:

Sections

  Show packages belonging to the selected section, only.

Status

  Show packages of the selected status, only.

Origin

  Show only enabled repositories.

Custom Filters

  Show packages that fit to the selected custom criteria, only.

Search Results

  Show the results of the selected search, only.

Architecture

  Show all available computer architecture.

### Package List

The package list shows the packages of the selected category.

#### Package List

Shows the package list in the &app; main window.

The used status icons are explained in the icon legend. To open the legend choose Help Icon Legend from the menu.

The column order and the used colors can be changed in the preferences.

### Package Properties

To open the properties dialog of a selected package:

- Choose Package Properties from the menu

- Click on Properties in the toolbar

- Press the key combination Ctrl O

#### Package Properties Dialog

Shows the package details in the &app; main window.

The notebook provides the following tabs:

#### Tabs in the properties dialog

Tab | Description
--- | ---
Common | Shows basic information of the package: name, short description, maintainer, status, priority, tags (if supported) and version.
Dependencies | Lists required, depending, provided, suggested and recommended packages.
Installed Files | Shows installed files for installed packages.
Versions | Shows available versions of the package.
Description | Shows a long description of the package.

## Managing Packages

This chapter covers the basic actions , and of packages.

Furthermore performing a , the online documentation, the changelog and the advanced actions the installation of a specific package version, a package to the current version are described.

### To Install Packages

If different version of the same package are available &app; will select the most applicable by default. To force the installation of a specific version that is different to the default one, see .

If you want to install a package perform the following steps:

1. Reload the package information to be aware of the latest versions available:

   - Choose Edit Reload Package Information from the menu.

   - Click on Reload in the toolbar.

   - Press the key combination Ctrl R.

2. Mark the package for installation:

   - Double click on the name of the package in the .

   - Click on the status icon of the package and choose Mark for Installation from the menu.

   - Right click on the package and choose Mark for Installation from the context menu.

   - Select the package and choose Package Mark for Installation from the menu.

   - Select the package and press the key combination Ctrl I.

   If the installation of the package(s) requires additional changes, you will be asked for confirmation. To also mark the additional changes click on the button Mark .

3. Apply the marked changes to actually install the package:

   - Click on Apply in the toolbar.

   - Choose Edit Apply Marked Changes from the menu.

   - Press the key combination Ctrl P.

4. You will be asked for confirmation. Check the summarized changes that will be applied. To continue with the actual installation confirm the changes click on Apply.

5. During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

   The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

### To Remove Packages

Configuration files and user created data (e.g. a website in "/var/www") are not removed from the system by default.

Debian only: You can change the default behavior in the preferences.

Debian only: To remove all files related to the package choose Mark for Complete Removal instead of Mark for Removal.

To remove a packages follow these steps:

1. Mark the package for removal:

   - Double click on the name of the installed package in the .

   - Click on the status icon of the package and choose Mark for Removal from the menu.

   - Right click on the package and choose Remove from the context menu.

   - Select the package and choose Package Mark for Removal from the menu.

   - Select the package and press the key Delete.

   If the removal of the package(s) requires additional changes, you will be asked for confirmation. To also mark the additional changes click on the button Mark .

2. Apply the marked changes to actually remove the package(s):

   - Click on Apply in the toolbar.

   - Choose Edit Apply Marked Changes from the menu.

   - Press the key combination Ctrl P.

3. You are asked for confirmation. Check the summarized changes that will be applied. To continue with the actual removal confirm the changes click on Apply.

4. During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

   The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

### To Upgrade Packages

To upgrade a package follow these steps:

1. Reload the package information to be aware of the latest versions available:

   - Choose Edit Reload Package Information from the menu.

   - Click on Reload in the toolbar.

   - Press the key combination Ctrl R.

2. Mark the package for upgrade:

   - Double click on the name of the package with a later version available in the .

   - Click on the status icon of the package and choose Mark for Upgrade from the menu.

   - Right click on the package and choose Mark for Upgrade from the context menu.

   - Select the package and choose Package Mark for Upgrade from the menu.

   - Select the package and press the key combination Ctrl P.

   If the upgrade of the package(s) requires additional changes, you will be asked for confirmation. To also mark the additional changes click on the button Mark .

3. Apply the marked changes to actually upgrade the package:

   - Click on Apply in the toolbar.

   - Choose Edit Apply Marked Changes from the menu.

   - Press the key combination Ctrl P.

4. You are asked for confirmation. Check the summarized changes that will be applied. To continue with the actual upgrade confirm the changes click on Apply.

5. During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

   The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

To upgrade all installed packages to the latest version, see .

### To Upgrade the Whole System

&app; provides two methods for marking packages for upgrade:

Default Upgrade

  The default upgrade method marks upgrades of installed packages only. If the later version of a package depends on not installed packages or conflicts with an already installed package, the upgrade will not be marked.

Smart Upgrade (Dist-Upgrade)

  The smart upgrade method tries to resolve package conflicts intelligently. This includes installing additional required packages and preferring packages with higher priority.

  Smart upgrade is also known as dist-upgrade in the console tool apt-get.

Upgrades to a later operating system major releases have to be performed with the smart upgrade method, e.g. from Conectiva 9 to Conectiva 10 or from Debian Woody to Debian Sarge.

To upgrade your system to the latest version follow these steps:

1. Reload the package information to be aware of the latest versions available:

   - Choose Edit Reload Package Information from the menu.

   - Click on Reload in the toolbar.

   - Press the key combination Ctrl R.

2. Mark all possible upgrades:

   - Click on Mark all Upgrades in the toolbar.

   - Choose Edit Mark all Upgrades from the menu.

   - Press the key combination Ctrl G.

3. Choose the upgrade method. Smart upgrade is recommended.

4. Apply the marked changes to actually upgrade the package(s):

   - Click on Apply in the toolbar.

   - Choose Edit Apply Marked Changes from the menu.

   - Press the key combination Ctrl P.

5. You are asked for confirmation. Check the summarized changes that will be applied. To continue with the actual upgrade confirm the changes click on Apply.

6. During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

   The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

You can change the default upgrade method for further upgrade in the preferences .

### To Apply Marked Changes

To show packages that are marked for a status change only choose the "Marked Changes" filter, see .

To apply marked changes:

- Click on Apply in the toolbar.

- Choose Edit Apply Marked Changes from the menu.

- Press the key combination Ctrl P.

You are asked for confirmation. Check the summarized changes that will be applied. To confirm the changes click on the button Apply.

During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

### To Unmark Changes

The following ways allow you to unmark changes:

To undo the marking of specific packages

  - Right click on the package and choose Unmark from the context menu.

  - Select the package(s) and choose Package Unmark .

  - Select the package(s) and press Ctrl N.

To undo all markings

  Choose Edit Unmark All from the menu.

To undo the last marking

  Choose Edit Undo from the menu.

  This step can be repeated. The maxmium number of undo operations can be set in the preferences. FIX link

### To Configure Packages (Debian only)

To use this feature you have to install the package libgnome2-perl.

Debian provides a unified method, called debconf, to configure software packages. This feature is not supported by all packages. If a package supports this feature the configuration can be done through an assistant.

To configure a supported package:

1. Select the package that you wish to configure in the .

2. Choose Package Configure... from the menu.

To get a list of all configurable packages choose the Configurable Packages filter.

### To View Documentation for Packages (Debian only)

To use this feature you have to install the package dwww.

Dwww provides access to all the installed documentation related to package with a web browser. The whole documentation is hosted via a local HTTP server.

1. Select the package about that you wish to read additional documentation in the .

2. Choose Package Browse Documentation.

### To View the Changelog of a Package (Debian only)

The changelog of native Debian packages can be viewed, only.

To view the changelog of a native Debian package perform the following steps:

1. Select the package in the .

2. Choose Package Download Changelog.

### To Lock a Package to the Current Version (Debian only)

To lock a package to the current version follow these steps:

1. Select the package that you want to lock in the .

2. Choose Package Lock Version.

   The &app; will reload the package information. You should now see, that the menu item Package Lock Version is checked. Furthermore all actions in the menu Package are disabled now.

To unlock the package uncheck Package Lock Version .

### To Force the Installation of a Specific Version

The &app; always selects the most applicable version available. If you force a different version from the default one, errors in the dependency handling can occur.

To force the installation of a version of package different to the default one perform the following steps:

1. Reload the package information to be aware of the latest versions available:

   - Choose Edit Reload Package Information from the menu.

   - Click on Reload in the toolbar.

   - Press the key combination Ctrl R.

2. Select the package in the .

3. Choose Package Force Version... from the menu to open a dialog with all available versions of the package.

4. Select the version that should be marked for installation. To confirm your decision click on the button Force.

5. Apply the marked changes to actually install the forced package version:

   - Click on Apply in the toolbar.

   - Choose Edit Apply Marked Changes from the menu.

   - Press the key combination Ctrl P.

6. You will be asked for confirmation. Check the summarized changes that will be applied. To continue with the actual installation confirm the changes click on Apply

7. During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

   The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

### To Fix Broken Packages

&app; will not allow any further changes to the system before all broken packages are fixed.

To show all broken packages choose the Broken filter.

To correct the broken packages perform the following steps: choose Edit Fix Broken Packages from the menu.

1. Choose Edit Fix Broken Packages from the menu.

2. Apply the marked changes to actually fix the packages:

   - Click on Apply in the toolbar.

   - Choose Edit Apply Marked Changes from the menu.

   - Press the key combination Ctrl E.

3. You will be asked for confirmation. Check the summarized changes that will be applied. To continue with the actual repair confirm the changes click on Apply

4. During the processing of the changes you will see a progressbar. Wait until the changes have been applied. This can take some time depending on the number of changes. Afterwards you will be returned to the main window.

   The progressbar is not available on Debian system. Instead you will see a detailed terminal output.

## Repositories

Packages are made available through so called repositories. The repository contains the packages and an index which includes some basic information about the packages, e.g. required dependencies or a short description.

Repositories can be located on many medias: CD-Rom/DVD, local hard disk, the Web (http,ftp) or remote file system (nfs).

### To Reload the Package Information

To collect the list of all available packages from the repositories choose one of the following methods:

- Choose Edit Reload Package Information from the menu.

- Click on Reload in the toolbar.

### To Edit, Add or Remove Repositories

You can edit, add or delete repositories in the repository preferences.

Open the repository editor with Settings Repositories from the menu.

#### Repository Preferences

Shows the repository preferences

### To Add Repositories From CD-ROM

Choose Edit Add CD... from the menu.

### The Syntax of the APT line

The package manager stores all available repositories in a text based configuration file. Each line describes the type, location and content of one repository.

#### Syntax of an APT line e.g. deb http://ftp.debian.org sarge main

Element | Description
--- | ---
deb | The first elements describes the type of the repository. Possible values are deb (Debian binary packages), deb-src (Debian source packages), rpm (RPM binary packages), rpm-src (Redhat source packages), rpmdir (folder that contains RPM binary packages) and rpmdir-src (folder that contains RPM source packages).
http://ftp.debian.org | The second element is the location of the repository. The repository can be accessed by the protocols HTTP and FTP, or locally on a CD, DVD or hard disk.
sarge | The third element describes the distribution for which the packages are made for, see the Debian Developer's Reference for more details on distributions of Debian.
main | The forth element describes sections of the repository that should be included. By default official Debian repositories are separated into the sections main, contrib and non-free, see the Debian Developer's Reference for more details on sections of Debian.

The distribution and section element are not required for each type.

## Custom Filters

Filters enable you to narrow down the list of shown packages by a variety of package attributes.

&app; comes with a set of predefined filters.

### Predefined Filters

Filter | Description
--- | ---
All packages | Display all known packages.
Marked Changes | Display all packages that are marked for a status change.
Pkg with Debconf | Display all packages that can be configured through debconf (Debian only).
Broken | Display only packages with broken dependencies.
Upgradable (upstream) | Display all packages that can be upgraded to a later upstream version.

Because of some interface changes the set of predefined filters changed, too. The old and deprecated filters are not removed automatically by Synaptic.

### Deprecated Filters

Filter | Description
--- | ---
Install | Display only currently installed packages.
Not installed | Display only currently not installed packages.
Upgradable | Display only packages with a later version available.
Broken | Display only packages with broken dependencies.
Programmed Changes | Display only packages marked to be modified.
New in archive | Display only new packages since the last repository update.
Residual | Display only former installed packages that left data or configuration files on the system.
Pkg with Debconf | Display only packages that can be configured through the debian package configuration system, so called debconf.
Obsolete or locally installed | Display only packages that are not (for longer) included in one of the specified repositories.
Search Filter | Display the results of the last package search.

### To Apply Filters

To apply a filter follow these steps:

1. Choose Custom Filters from the category combobox in the main window.

2. Choose the wished filter from the .

### To Edit or Create Custom Filters

Filters can be created, deleted and modified in the filter editor:

Choose Settings Filters from the menu.

#### Edit Filters

Shows the filter editor.

The filter editor contains the following components:

List of Filter

  Shows a list of available filters.

Rules

  Rules allow you to define which packages should be shown in the list. A package has to fulfill all selected criteria.

  Status

    Allows you to search packages by status.

  Section

    Allows you to search packages by section.

  Properties

    Allows you to search packages by a variety of attributes e.g. name, dependencies or origin.

  Keywords

    Keywords are based on debtags. Only Debian GNU/Linux with installed "debtags" supports this feature.

## Known Bugs and Limitations

### Known issues and workarounds

Problem | Workaround
--- | ---
Unsupported locale | Use a locale supported by Xlib.

A failed installation blocks further operations in synaptic

Under some rare circumstances the actual installation or removal of a package can fail. As a consequence all other marked changes are canceled, too.

&app; requires a clear environment with no half installed packages to perform additional changes. But at the moment there is no way to continue canceled installations within &app;.

To fix this situation type the following command in a terminal, then press Return:

`apt-get install -f`

## Keyboard Shortcuts

List of all global short cuts in &app;:

Reload the list of known packages | Ctrl R
Open the package search dialog | Ctrl F
Open the properties dialog for the selected package | Ctrl O
Mark the selected package(s) for installation | Ctrl I
Mark the selected package(s) for upgrade | Ctrl U
Mark the selected package(s) for removal | Delete
Mark the selected package(s) for complete removal (Debian only) | Shift Delete
Unmark any changes to the selected package(s) | Ctrl N
Mark all possible upgrades | Ctrl G
Force the installation of a specific version of the package | Ctrl E
Undo the last status change to a package and to the therefor required dependencies | Ctrl Z
Redo the last reverted status change to a package and to the therefor required dependencies | Shift Ctrl Z
Apply all marked changes | Ctrl P
Quit &app; | Ctrl Q
Show the manual of &app; | F1

## About &app;

&app; was originally written by Alfredo K. Kojima (kojima@windowmaker.org) and is now maintained by Michael Vogt (mvo@debian.org) and Gustavo Niemeyer (niemeyer@conectiva.com). To get more information about &app;, please visit the Synaptic Web Page.

To report a bug or make a suggestion regarding &app; or this manual, use the bug report system on the Synaptic Web Site, contact the mailing list synaptic@nongnu.org or join the IRC channel #synaptic on irc.freenode.org.

This program is distributed under the terms of the GNU Public license as published by the Free Software; either version 2 of the License, or (at your option) later version. A copy of this license can be found in , or in the file included with the source code of this program.

&legal;