pkg.8
1 .\" 2 .\" FreeBSD pkg - a next generation package for the installation and maintenance 3 .\" of non-core utilities. 4 .\" 5 .\" Redistribution and use in source and binary forms, with or without 6 .\" modification, are permitted provided that the following conditions 7 .\" are met: 8 .\" 1. Redistributions of source code must retain the above copyright 9 .\" notice, this list of conditions and the following disclaimer. 10 .\" 2. Redistributions in binary form must reproduce the above copyright 11 .\" notice, this list of conditions and the following disclaimer in the 12 .\" documentation and/or other materials provided with the distribution. 13 .\" 14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24 .\" SUCH DAMAGE. 25 .\" 26 .\" @(#)pkg.8 27 .\" 28 .Dd December 13, 2025 29 .Dt PKG 8 30 .Os 31 .\" --------------------------------------------------------------------------- 32 .Sh NAME 33 .Nm pkg , 34 .Nm pkg-static 35 .Nd manipulate packages 36 .\" --------------------------------------------------------------------------- 37 .Sh SYNOPSIS 38 .Nm 39 .Op Fl v 40 .Op Fl d 41 .Op Fl l 42 .Op Fl N 43 .Op Fl o Ao option=value Ac 44 .Op Fl j Ao jail name or id Ac | Fl c Ao chroot path Ac | Fl r Ao root directory Ac 45 .Op Fl C Ao configuration file Ac 46 .Op Fl R Ao repository configuration directory Ac 47 .Op Fl 4 | Fl 6 48 .Ao command Ac Ao Ar flags Ac 49 .Pp 50 .Nm 51 .Op Cm --version 52 .Op Cm --debug 53 .Op Cm --list 54 .Op Fl N 55 .Op Cm --option Ao option=value Ac 56 .Op Cm --jail Ao jail name or id Ac | Cm --chroot Ao chroot path Ac | Cm --rootdir Ao root directory Ac 57 .Op Cm --config Ao configuration file Ac 58 .Op Cm --repo-conf-dir Ao repository configuration directory Ac 59 .Op Fl 4 | Fl 6 60 .Ao command Ac Ao Ar flags Ac 61 .\" --------------------------------------------------------------------------- 62 .Sh DESCRIPTION 63 .Nm pkg 64 provides an interface for manipulating packages: registering, 65 adding, removing and upgrading packages. 66 .Nm pkg-static 67 is a statically linked variant of 68 .Nm 69 typically only used for the initial installation of 70 .Nm . 71 There are some differences in functionality. 72 See 73 .Xr pkg.conf 5 74 for details. 75 .\" --------------------------------------------------------------------------- 76 .Sh OPTIONS 77 The following options are supported by 78 .Nm : 79 .Bl -tag -width indent 80 .It Fl v , Cm --version 81 Display the current version of 82 .Nm . 83 Specify twice 84 .Pq Fl vv 85 to also show 86 .Xr pkg.conf 5 87 configuration. 88 .It Fl d , Cm --debug 89 Show debug information. 90 .It Fl l , Cm --list 91 List all the available command names, and exit without performing any 92 other action. 93 The 94 .Fl v 95 option takes precedence over 96 .Fl l 97 but 98 .Fl l 99 will override any other command line arguments. 100 .It Fl o Ao option=value Ac , Cm --option Ao option=value Ac 101 Set configuration option for 102 .Nm 103 from the command line. 104 Options that are set from the environment are redefined. 105 It is permitted to specify this option multiple times. 106 .It Fl N 107 Activation status check mode. 108 Prevent 109 .Nm 110 from automatically creating or initializing the SQLite database in 111 .Pa /var/db/pkg/local.sqlite 112 if it does not already exist. 113 .Pp 114 Prevent 115 .Nm 116 from performing any actions if no packages are currently installed, on 117 the basis that a correctly initialised system using 118 .Nm 119 will always have at least the 120 .Nm 121 package itself registered. 122 .Pp 123 If used without any other arguments, 124 .Nm Fl N 125 will run the sanity tests and if successful print out a short message 126 showing how many packages are currently installed. 127 The exit status should be a reliable indication of whether a system 128 is configured to use 129 .Nm 130 as its package management system or not. 131 .Pp 132 Example usage: 133 .Bd -literal -offset indent 134 if pkg -N >/dev/null 2>&1; then 135 # pkg(8) specific commands 136 else 137 # other package management system commands 138 fi 139 .Ed 140 .Pp 141 The 142 .Fl N 143 flag was first released in the 144 .Pa /usr/sbin/pkg 145 bootstrapper 146 in 147 .Fx 8.4 , 148 but was missing from 149 .Fx 9.1 . 150 It may not be enough to just call 151 .Nm Fl N , 152 as the bootstrapper may be invoked, or an error returned 153 from 154 .Nm . 155 The following script is the safest way to detect if 156 .Nm 157 is installed and activated: 158 .Bd -literal -offset indent 159 if TMPDIR=/dev/null ASSUME_ALWAYS_YES=yes \\ 160 PACKAGESITE=file:///nonexistent \\ 161 pkg info -x 'pkg(-devel)?$' >/dev/null 2>&1; then 162 # pkg(8) specific commands 163 else 164 # other package management system commands 165 fi 166 .Ed 167 .It Fl j Ao jail name or id Ac , Cm --jail Ao jail name or id Ac 168 .Nm 169 will execute in the given 170 .Ao jail name or id Ac , 171 where 172 .Em name 173 matches 174 .Dq Cm jls Ar name 175 and 176 .Em id 177 matches 178 .Dq Cm jls Ar jid . 179 See 180 .Xr jail 8 181 and 182 .Xr jls 8 . 183 .It Fl c Ao chroot path Ac , Cm --chroot Ao chroot path Ac 184 .Nm 185 will chroot in the 186 .Ao chroot path Ac 187 environment. 188 .It Fl r Ao root directory Ac , Cm --rootdir Ao root directory Ac 189 .Nm 190 will install all packages within the specified 191 .Ao root directory Ac . 192 .It Fl C Ao configuration file Ac , Cm --config Ao configuration file Ac 193 .Nm 194 will use the specified file as a configuration file. 195 .It Fl R Ao repo conf dir Ac , Cm --repo-conf-dir Ao repo conf dir Ac 196 .Nm 197 will search the directory for per-repository configuration files. 198 This overrides any value of 199 .Ev REPOS_DIR 200 specified in the main configuration file. 201 .It Fl 4 202 .Nm 203 will use IPv4 for fetching repository and packages. 204 .It Fl 6 205 .Nm 206 will use IPv6 for fetching repository and packages. 207 .El 208 .\" --------------------------------------------------------------------------- 209 .Sh COMMANDS 210 The following commands (or their unambiguous abbreviations) are supported by 211 .Nm : 212 .Bl -tag -width indent 213 .It Ic help Ar command 214 Display usage information of the specified command. 215 .It Ic add 216 Install a package from either a local source or a remote one. 217 .Pp 218 When installing from remote source you need to specify the 219 protocol to use when fetching the package. 220 .Pp 221 Currently supported protocols are FTP, HTTP and HTTPS. 222 .It Ic annotate 223 Add, modify or delete tag-value style annotations on packages. 224 .It Ic alias 225 List the command line aliases. 226 .It Ic audit 227 Audit installed packages against known vulnerabilities. 228 .It Ic autoremove 229 Delete packages which were automatically installed as dependencies and are not required any more. 230 .It Ic bootstrap 231 This is for compatibility with the 232 .Xr pkg 7 233 bootstrapper. 234 If 235 .Nm 236 is already installed, nothing is done. 237 .Pp 238 If invoked with the 239 .Fl f 240 flag an attempt will be made to reinstall 241 .Nm 242 from remote repository. 243 .It Ic check 244 Sanity checks installed packages. 245 .It Ic clean 246 Clean the local cache of fetched remote packages. 247 .It Ic create 248 Create a package. 249 .It Ic delete 250 Delete a package from the database and the system. 251 .It Ic fetch 252 Fetch packages from a remote repository. 253 .It Ic info 254 Display information about installed packages and package files. 255 .It Ic install 256 Install a package from a package repository or a local archive. 257 If a package is found in more than one repository, then the 258 first one is used. 259 If not local, then download is attempted from each repository, 260 until the package is successfully fetched. 261 .It Ic lock 262 Prevent modification or deletion of a package. 263 .It Ic plugins 264 List the available plugins. 265 .It Ic query 266 Query information about installed packages and package files. 267 .It Ic register 268 Register a package in the database. 269 .It Ic repo 270 Create a local package repository for remote usage. 271 .It Ic rquery 272 Query information for remote repositories. 273 .It Ic search 274 Search for the given pattern in the remote package 275 repositories. 276 .It Ic set 277 Modify information in the installed database. 278 .It Ic shell 279 Open a SQLite shell to the local or remote database. 280 Extreme care should be taken when using this command. 281 .It Ic shlib 282 Displays which packages link to a specific shared library. 283 .It Ic stats 284 Display package database statistics. 285 .It Ic unlock 286 Unlocks packages, allowing them to be modified or deleted. 287 .It Ic update 288 Update the available remote repositories as listed in 289 .Xr pkg.conf 5 . 290 .It Ic updating 291 Display UPDATING entries of installed packages. 292 .It Ic upgrade 293 Upgrade a package to a newer version. 294 .It Ic version 295 Summarize installed versions of packages. 296 .It Ic which 297 Query the database for package(s) that installed a specific 298 file. 299 .El 300 .\" --------------------------------------------------------------------------- 301 .Sh ENVIRONMENT 302 All configuration options from 303 .Xr pkg.conf 5 304 can be passed as environment variables. 305 .Pp 306 Extra environment variables are: 307 .Bl -tag -width "INSTALL_AS_USER" 308 .It INSTALL_AS_USER 309 Allow all manipulation to be done as a regular user instead of checking for 310 root credentials when appropriate. 311 .br 312 It is expected that the user will ensure that every file and directory 313 manipulated by 314 .Nm 315 are readable 316 .Pq or writable where appropriate 317 by the user. 318 .El 319 .\" --------------------------------------------------------------------------- 320 .Sh FILES 321 See 322 .Xr pkg.conf 5 . 323 .\" --------------------------------------------------------------------------- 324 .Sh EXAMPLES 325 Search for a package: 326 .Dl % pkg search perl 327 .Pp 328 Install a package: 329 .Dl Installing must specify a unique origin or version otherwise it will try installing all matches. 330 .Pp 331 .Dl % pkg install perl-5.14 332 .Pp 333 List installed packages: 334 .Dl % pkg info 335 .Pp 336 Upgrade from remote repository: 337 .Dl % pkg upgrade 338 .Pp 339 Change the origin for an installed package: 340 .Dl % pkg set -o lang/perl5.12:lang/perl5.14 341 .Dl % pkg install -Rf lang/perl5.14 342 .Pp 343 List non-automatic packages: 344 .Dl % pkg query -e '%a = 0' %o 345 .Pp 346 List automatic packages: 347 .Dl % pkg query -e '%a = 1' %o 348 .Pp 349 Delete an installed package: 350 .Dl % pkg delete perl-5.14 351 .Pp 352 Remove unneeded dependencies: 353 .Dl % pkg autoremove 354 .Pp 355 Change a package from automatic to non-automatic, which will prevent 356 .Ic autoremove 357 from removing it: 358 .Dl % pkg set -A 0 perl-5.14 359 .Pp 360 Change a package from non-automatic to automatic, which will make 361 .Ic autoremove 362 allow it be removed once nothing depends on it: 363 .Dl % pkg set -A 1 perl-5.14 364 .Pp 365 Create package file from an installed package: 366 .Dl % pkg create -o /usr/ports/packages/All perl-5.14 367 .Pp 368 Determine which package installed a file: 369 .Dl % pkg which /usr/local/bin/perl 370 .Pp 371 Audit installed packages for security advisories: 372 .Dl % pkg audit 373 .Pp 374 Check installed packages for checksum mismatches: 375 .Dl # pkg check -s -a 376 .Pp 377 Check for missing dependencies: 378 .Dl # pkg check -d -a 379 .Pp 380 Show the pkg-message of a package: 381 .Dl # pkg info -D perl-5.14 382 .Pp 383 Restore a backup database: 384 .Dl % rm /var/db/pkg/local.sqlite 385 .Dl % xzcat /var/backups/pkg.sql.xz | pkg shell 386 .\" --------------------------------------------------------------------------- 387 .Sh SEE ALSO 388 .Xr pkg_create 3 , 389 .Xr pkg_printf 3 , 390 .Xr pkg_repo_create 3 , 391 .Xr pkg_repos 3 , 392 .Xr pkg-keywords 5 , 393 .Xr pkg-lua-script 5 , 394 .Xr pkg-repository 5 , 395 .Xr pkg-script 5 , 396 .Xr pkg-triggers 5 , 397 .Xr pkg.conf 5 , 398 .Xr pkg-add 8 , 399 .Xr pkg-alias 8 , 400 .Xr pkg-annotate 8 , 401 .Xr pkg-audit 8 , 402 .Xr pkg-autoremove 8 , 403 .Xr pkg-check 8 , 404 .Xr pkg-clean 8 , 405 .Xr pkg-config 8 , 406 .Xr pkg-create 8 , 407 .Xr pkg-delete 8 , 408 .Xr pkg-fetch 8 , 409 .Xr pkg-help 8 , 410 .Xr pkg-info 8 , 411 .Xr pkg-install 8 , 412 .Xr pkg-key 8 , 413 .Xr pkg-lock 8 , 414 .Xr pkg-plugins 8 , 415 .Xr pkg-query 8 , 416 .Xr pkg-register 8 , 417 .Xr pkg-repo 8 , 418 .Xr pkg-repositories 8 , 419 .Xr pkg-rquery 8 , 420 .Xr pkg-search 8 , 421 .Xr pkg-set 8 , 422 .Xr pkg-shell 8 , 423 .Xr pkg-shlib 8 , 424 .Xr pkg-ssh 8 , 425 .Xr pkg-stats 8 , 426 .Xr pkg-triggers 8 , 427 .Xr pkg-unregister 8 , 428 .Xr pkg-update 8 , 429 .Xr pkg-updating 8 , 430 .Xr pkg-upgrade 8 , 431 .Xr pkg-version 8 , 432 .Xr pkg-which 8 433 .Pp 434 To build your own package set for one or multiple servers see 435 .Bl -tag -width "" 436 .It Lk "https://pkg.freebsd.org" "FreeBSD pkg mirror" 437 Your closest pkg mirror based on MaxMind GeoLite geo-DNS. 438 .El 439 .\" --------------------------------------------------------------------------- 440 .Sh HISTORY 441 The 442 .Nm 443 command first appeared in 444 .Fx 9.1 . 445 .\" --------------------------------------------------------------------------- 446 .Sh AUTHORS AND CONTRIBUTORS 447 .An Baptiste Daroussin Aq bapt@FreeBSD.org , 448 .An Julien Laffaye Aq jlaffaye@FreeBSD.org , 449 .An Philippe Pepiot Aq phil@philpep.org , 450 .An Will Andrews Aq will@FreeBSD.org , 451 .An Marin Atanasov Nikolov Aq dnaeon@gmail.com , 452 .An Yuri Pankov Aq yuri.pankov@gmail.com , 453 .An Alberto Villa Aq avilla@FreeBSD.org , 454 .An Brad Davis Aq brd@FreeBSD.org , 455 .An Matthew Seaman Aq matthew@FreeBSD.org , 456 .An Bryan Drewery Aq bryan@shatow.net , 457 .An Eitan Adler Aq eadler@FreeBSD.org , 458 .An Romain Tarti\[`e]re Aq romain@FreeBSD.org , 459 .An Vsevolod Stakhov Aq vsevolod@FreeBSD.org , 460 .An Alexandre Perrin Aq alex@kaworu.ch 461 .\" --------------------------------------------------------------------------- 462 .Sh BUGS 463 See the issue tracker at 464 .Em https://github.com/freebsd/pkg/issues . 465 .Pp 466 Please direct questions and issues to the 467 .An pkg@FreeBSD.org 468 mailing list.