home | help 
bpkg-pkg-status(1)	     General Commands Manual	      bpkg-pkg-status(1)

NAME
     bpkg-pkg-status - print package status

SYNOPSIS
     bpkg pkg-status|status [options] [pkg[/ver]...]

DESCRIPTION
     The  pkg-status  command prints the status of the specified packages or, if
     ver is specified, package versions. If no	packages  were	specified,  then
     pkg-status  prints the status of all the held packages (which are the pack-
     ages that were explicitly built; see bpkg-pkg-build(1)).  The  latter  mode
     can  be  modified to print the status of all the packages by specifying the
     --all|-a option. Additionally, the status of immediate or all  dependencies
     (and dependency constraints) of the above packages can be printed by speci-
     fying the --immediate|-i or --recursive|-r options, respectively. Note that
     the status is written to stdout, not stderr.

     The  default output format (see the --stdout-format common option) is regu-
     lar with components separated with spaces. Each line starts with the  pack-
     age name followed by one of the status words listed below. Some of them can
     be  optionally  followed  by  ',' (no spaces) and a sub-status word.  Lines
     corresponding to dependencies from linked configurations will  additionally
     mention  the  configuration  directory in square brackets after the package
     name. Lines corresponding to dependency constraints will have  the  package
     name prefixed with '?'.

     unknown
	    Package  is  not part of the configuration nor available from any of
	    the repositories.

     available
	    Package is not part of the configuration but is available  from  one
	    of the repositories.

     fetched
	    Package is part of the configuration and is fetched.

     unpacked
	    Package is part of the configuration and is unpacked.

     configured
	    Package  is part of the configuration and is configured. May be fol-
	    lowed by the system sub-status indicating a package coming from  the
	    system.  The  version of such a system package (described below) may
	    be the special '*' value indicating a wildcard version.

     broken
	    Package is part of the configuration and is broken (broken	packages
	    can only be purged; see bpkg-pkg-purge(1)).

     If  only  the  package name was specified without the package version, then
     the available status word is followed by the list	of  available  versions.
     Versions  that  are  only available for up/down-grading are printed in '[]'
     (such version are only available as dependencies from prerequisite  reposi-
     tories  of  other	repositories). If the --system option is specified, then
     the last version in this list may have the sys: prefix indicating an avail-
     able system version. Such a system version may be the special '?' value in-
     dicating that a package may or may not be available  from	the  system  and
     that its version is unknown.

     The  fetched, unpacked, configured, and broken status words are followed by
     the version of the package. If the package version was specified, then  the
     unknown status word is also followed by the version.

     If  the  status  is fetched, unpacked, configured, or broken and newer ver-
     sions are available, then the package version is followed by the  available
     status  word  and the list of newer versions.  To instead see a list of all
     versions, including the older ones, specify the --old-available|-o  option.
     In this case the currently selected version is printed in '()'.

     If  the  package  name was specified with the version, then only the status
     (such as, configured, available, etc.) of this version is considered.

     If a package is being held, then its name is  printed  prefixed  with  '!'.
     Similarly,  if a package version is being held, then the version is printed
     prefixed with '!'. Held packages and held versions  were  selected  by  the
     user and are not automatically dropped and upgraded, respectively.

     Below  are  some examples, assuming the configuration has libfoo 1.0.0 con-
     figured and held (both package and version) as well  as  libfoo  1.1.0  and
     1.1.1 available from source and 1.1.0 from the system.

     bpkg status libbar
     libbar unknown

     bpkg status libbar/1.0.0
     libbar unknown 1.0.0

     bpkg status libfoo/1.0.0
     !libfoo configured !1.0.0

     bpkg status libfoo/1.1.0
     libfoo available 1.1.0

     bpkg status --system libfoo/1.1.0
     libfoo available 1.1.0 sys:1.1.0

     bpkg status libfoo
     !libfoo configured !1.0.0 available 1.1.0 1.1.1

     bpkg status libfoo/1.1.1 libbar
     libfoo available 1.1.1
     libbar unknown

     Assuming now that we dropped libfoo from the configuration:

     bpkg status libfoo/1.0.0
     libfoo unknown 1.0.0

     bpkg status libfoo
     libfoo available 1.1.0 1.1.1

     And assuming now that we built libfoo as a system package with the wildcard
     version:

     bpkg status libfoo
     !libfoo configured,system !* available 1.1.0 1.1.1

     Another  example  of the status output this time including dependencies and
     constraints:

     bpkg status -r libbaz
     !libbaz configured 1.0.0
       libfoo configured 1.0.0
	 bison [.bpkg/host/] configured 1.0.0
       libbar configured 2.0.0
       ?bison [.bpkg/host/] configured 1.0.0

     If the output format is json, then the output is a JSON  array  of  objects
     which  are  the serialized representation of the following C++ struct pack-
     age_status:

     struct available_version
     {
       string version;
       bool   system;
       bool   dependency;
     };

     struct package_status
     {
       string			 name;
       optional<string> 	 configuration;
       optional<string> 	 version_constraint;
       string			 status;
       optional<string> 	 sub_status;
       optional<string> 	 version;
       bool			 hold_package;
       bool			 hold_version;
       vector<available_version> available_versions;
       vector<package_status>	 dependencies;
       vector<package_status>	 constraints;
     };

     For example:

     [
       {
	 "name": "hello",
	 "status": "configured",
	 "version": "1.0.0",
	 "hold_package": true,
	 "available_versions": [
	   {
	     "version": "1.0.1"
	   },
	   {
	     "version": "2.0.0"
	   }
	 ],
	 "dependencies": [
	   {
	     "name": "libhello",
	     "status": "configured",
	     "version": "1.0.2",
	   }
	 ]
       }
     ]

     See the JSON OUTPUT section in bpkg-common-options(1) for	details  on  the
     overall  properties  of this format and the semantics of the struct serial-
     ization.

     In package_status, the configuration member contains the absolute directory
     of a linked configuration if this package resides in  a  linked  configura-
     tion.  The  version_constraint member is present only if the --version-con-
     straint option is specified. The version member is  absent  if  the  status
     member  is  unknown or available and no package version is specified on the
     command line. If the sub_status member is system, then the  version  member
     can  be  special  *.   The dependencies and constraints members are present
     only if the --immediate|-i or --recursive|-r options are specified.

     In available_version, if the system member is true, then  this  version  is
     available	from the system, in which case the version member can be special
     ? or *. If the dependency member is true, then this version is only  avail-
     able as a dependency from prerequisite repositories of other repositories.

PKG-STATUS OPTIONS
     --all|-a
	    Print the status of all the packages, not just held.

     --link Also  print  the  status of held/all packages from linked configura-
	    tions.

     --immediate|-i
	    Also print the status of immediate dependencies and constraints.

     --recursive|-r
	    Also print the status of all dependencies  and  constraints,  recur-
	    sively.

     --old-available|-o
	    Print old available versions.

     --version-constraint
	    Print version constraints for dependencies and constraints.

     --system
	    Check the availability of packages from the system.

     --no-hold
	    Don't print the package or version hold status.

     --no-hold-package
	    Don't print the package hold status.

     --no-hold-version
	    Don't print the version hold status.

     --directory|-d dir
	    Assume  configuration  is  in dir rather than in the current working
	    directory.

COMMON OPTIONS
     The common options are summarized below with a  more  detailed  description
     available in bpkg-common-options(1).

     -v     Print essential underlying commands being executed.

     -V     Print all underlying commands being executed.

     --quiet|-q
	    Run quietly, only printing error messages.

     --verbose level
	    Set the diagnostics verbosity to level between 0 and 6.

     --stdout-format format
	    Representation format to use for printing to stdout.

     --jobs|-j num
	    Number of jobs to perform in parallel.

     --no-result
	    Don't print informational messages about the outcome of performing a
	    command or some of its parts.

     --structured-result fmt
	    Write the result of performing a command in a structured form.

     --progress
	    Display  progress  indicators  for	long-lasting operations, such as
	    network transfers, building, etc.

     --no-progress
	    Suppress progress indicators for long-lasting  operations,	such  as
	    network transfers, building, etc.

     --diag-color
	    Use color in diagnostics.

     --no-diag-color
	    Don't use color in diagnostics.

     --build path
	    The build program to be used to build packages.

     --build-option opt
	    Additional option to be passed to the build program.

     --fetch path
	    The fetch program to be used to download resources (packages, repos-
	    itory metadata, etc).

     --fetch-option opt
	    Additional option to be passed to the fetch program.

     --fetch-timeout sec
	    The fetch and fetch-like (for example, git) program timeout.

     --offline
	    Do not attempt to download resources (packages, repository metadata,
	    etc),  instead  taking  them from the local fetch cache if available
	    and failing otherwise.

     --no-fetch-cache
	    Disable local caching of downloaded resources (packages,  repository
	    metadata, etc).

     --fetch-cache mode
	    Comma-separated list of local fetch cache modes.

     --fetch-cache-path dir
	    The directory of the local fetch cache.

     --fetch-cache-session id
	    The local fetch cache session.

     --sqlite-synchronous mode
	    Filesystem	synchronization  mode for the fetch cache and configura-
	    tion SQLite databases.

     --pkg-proxy url
	    HTTP proxy	server	to  use  when  fetching  package  manifests  and
	    archives from remote pkg repositories.

     --git path
	    The git program to be used to fetch git repositories.

     --git-option opt
	    Additional common option to be passed to the git program.

     --sha256 path
	    The sha256 program to be used to calculate SHA256 sums.

     --sha256-option opt
	    Additional option to be passed to the sha256 program.

     --tar path
	    The tar program to be used to extract package archives.

     --tar-option opt
	    Additional option to be passed to the tar program.

     --openssl path
	    The openssl program to be used for crypto operations.

     --openssl-option opt
	    Additional option to be passed to the openssl program.

     --auth type
	    Types of repositories to authenticate.

     --trust fingerprint
	    Trust repository certificate with a SHA256 fingerprint.

     --trust-yes
	    Assume the answer to all authentication prompts is yes.

     --trust-no
	    Assume the answer to all authentication prompts is no.

     --git-capabilities up=pc
	    Protocol capabilities (pc) for a git repository URL prefix (up).

     --pager path
	    The pager program to be used to show long text.

     --pager-option opt
	    Additional option to be passed to the pager program.

     --options-file file
	    Read additional options from file.

     --default-options dir
	    The directory to load additional default options files from.

     --no-default-options
	    Don't load default options files.

     --keep-tmp
	    Don't  remove  the bpkg's temporary directory at the end of the com-
	    mand execution and print its  path	at  the  verbosity  level  2  or
	    higher.

DEFAULT OPTIONS FILES
     See  bpkg-default-options-files(1)  for  an overview of the default options
     files. For the pkg-status command the search start directory is the config-
     uration directory. The following options files are searched for in each di-
     rectory and, if found, loaded in the order listed:

     bpkg.options
     bpkg-pkg-status.options

     The following pkg-status command options cannot be specified in the default
     options files:

     --directory|-d

BUGS
     Send bug reports to the users@build2.org mailing list.

COPYRIGHT
     Copyright (c) 2014-2026 the build2 authors.

     Permission is granted to copy, distribute and/or modify this document under
     the terms of the MIT License.

bpkg 0.18.0			   April 2026		      bpkg-pkg-status(1)
home | help