*! version 2.0.0 25jul2026

help for usepackagev 2.0.0

Title

usepackage -- find, verify, and install the user-written packages
(and data) a do-file needs

Syntax

usepackage pkgname [pkgname ...]
[, options]

usepackage pkgname , github(owner/repo)
[options]

usepackage [*] , github(owner)
- list the packages an account or repository ships

usepackage , data(owner/repo)
[files(filelist) options]

Which packages
update reinstall the listed packages even if already present

nearest also consider similarly named packages

from(url) install from this net source, skipping the search

Confirmation and reporting
noconfirm accept inferred matches without asking

dryrun report what would happen; install nothing

Ancillary files
noancillary do not fetch ancillary files (default is to fetch them)

GitHub
github(owner/repo) install a package from a GitHub repository, or from owner alone to search that account

ghowner(owners) accounts to search when a name is on neither SSC nor the catalogue

data(owner/repo) fetch data files from a GitHub repository

files(filelist) which repository files to fetch

branch(name) branch to use (default: try main, then master)

into(dir) directory to fetch data into (default: current)

useit load the fetched dataset when exactly one was fetched

Auditing a do-file
scan(filename) report commands in a do-file that do not resolve

Description

usepackage takes a list of user-written packages a do-file needs and makes
sure they are installed, so a shared do-file can begin with one line instead of
a stack of ssc install and net install commands, or a
paragraph of instructions telling the reader to go run findit.

For each name it works through, in order: is it already installed; is it on
SSC; and failing that, does
the net search catalogue know it (which covers the
Stata Journal and the Stata Technical Bulletin). It reports what it
found, what it skipped, and why, and finishes with a one-line tally.

The name you ask for is often a command rather than a package:
dropmiss ships inside package dm89_2, bacon inside
st0197. usepackage recognises that case, but because the mapping is
inferred it asks before installing (see below
and noconfirm).

usepackage is partly inspired by the LaTeX command of the same name.

Options

update reinstalls each listed package even when it is already present.
Without it, an installed package is left alone and reported as such.

nearest widens the search: after looking for a package of that name and
for a package whose description mentions that command, usepackage will also
offer the closest name it saw in the catalogue. Because that match is a guess, it
is always offered for confirmation, never installed silently.

from(url) installs from a net source directly and skips
searching. Use it when you already know where a package lives.

noconfirm accepts inferred matches without asking. Use it when running
unattended. In a batch run usepackage will not prompt: without
noconfirm an inferred match is reported and left uninstalled, rather than
hanging on a question nobody can answer.

dryrun reports what would be installed, from where, and whether
ancillary files are involved, without changing anything. Good for checking a
do-file's dependency list before handing it to someone.

noancillary suppresses ancillary files. See
Ancillary files.

github(owner/repo) installs a package from a GitHub
repository. See GitHub packages.

data(owner/repo), files(), into(),
useit fetch data. See GitHub data.

branch(name) pins the branch. By default main is tried
first, then master.

scan(filename) reads a do-file and lists the commands in it that
do not resolve on this machine, so you can see what a collaborator would be
missing before you send it. It reports; it never installs.

Ancillary files

Stata splits a package's contents in two. Installation files are copied onto
your adopath by net install. Ancillary files are not: they arrive
only with net get, and they land in the current directory. Which is
which is decided purely by extension: .ado, .sthlp, .mata,
.py and friends are installed; .do, .dta, .csv,
.xlsx, .html, .js are ancillary.

This is why findit spmap offers two separate links, and why
net describe st0535 lists 2 installation files against 26 ancillary ones
(the flowbca examples and their datasets).

usepackage fetches ancillary files by default, on the view that if a
package author shipped worked examples you probably want them. It says how many
arrived. Specify noancillary to skip them, in which case it tells you how
many exist and how to get them later:

. usepackage flowbca, noancillary

26 ancillary file(s) available; noancillary specified, so they were not fetched

to get them later: net get st0535

noancillary is worth reaching for when you are installing into a working
directory you would rather not fill with example datasets.

GitHub packages

github() installs from a GitHub repository. A repository is installable
when it carries a stata.toc and a pkgname.pkg manifest;
usepackage probes for them rather than making you work out the exact raw
URL. It tries branch main then master, and at each branch looks at
the repository root and then in ado/, src/, stata/ and
code/.

All of these are accepted:

. usepackage applyvarlabels, github("ericabooth/applyvarlabels-stata-public")

. usepackage sparkta2, github("texas-2036/sparkta2-stata-public")

. usepackage mypkg, github("https://github.com/owner/repo") // pasted URL

. usepackage mypkg, github("https://github.com/owner/repo/tree/main")

. usepackage mypkg, github("owner/repo.git")

. usepackage mypkg, github("owner/repo#dev") // pin a branch

. usepackage mypkg, github("owner/repo:ado") // files live in ado/

If no stata.toc turns up, usepackage says so and points you at
data(), since a repository of datasets is not a package.

Searching a whole account

You usually remember the command, not which repository it sits in. Give
github() a bare owner and usepackage works it out:

. usepackage editanything, github("texas-2036")

searching repositories owned by texas-2036

14 repositor(ies) listed; narrowing by name

matched texas-2036/EditAnything-stata-public in owner texas-2036

It lists the account's repositories in one request against the ordinary
GitHub API (60 an hour), not the code-search API (about 10 a minute), then
narrows by name before probing anything: an exactly matching repository name
first, then names beginning with the package name, then names containing it.

The distinction that decides whether you are asked: a repository containing a
pkgname.pkg has declared that it ships the package, which is
proof rather than resemblance, so it installs. A repository whose name merely
looks right but carries no matching .pkg is offered for confirmation.

Listing what an account (or a repository) ships

Leave the package name off, or give *, and github() becomes a
catalogue rather than an install:

. usepackage, github("texas-2036")

. usepackage *, github("texas-2036") // the same thing

14 repositor(ies); checking each for a stata.toc...

--------------------------------------------------------

package repository branch

--------------------------------------------------------

driveuse driveuse-stata-public main

editanything EditAnything-stata-public main

sparkta2 sparkta2-stata-public main

--------------------------------------------------------

5 package(s) in 5 repositor(ies); 9 have no stata.toc

The package names come from each repository's stata.toc, which is what
net install itself reads, so the list is what is genuinely installable
rather than a guess from file names. Repositories with no stata.toc are
counted but not listed. Point it at one repository instead to see just that:

. usepackage *, github("texas-2036/sparkta2-stata-public")

Searching your own accounts automatically

If you keep packages on GitHub, name the accounts once and stop typing
github() at all. Put this in profile.do:

global usepackage_github "ericabooth texas-2036"

and any name that is on neither SSC nor the net search catalogue is looked
for in those accounts, in order, before usepackage gives up:

. usepackage editanything

not found on SSC, and no match in the net search catalogue

searching repositories owned by ericabooth

matched ericabooth/EditAnything-stata-public in owner ericabooth

installed from https://raw.githubusercontent.com/...

ghowner() does the same for one call without setting the global. Both mean
a single mixed list can span SSC, the Stata Journal, and your own repositories:

. usepackage fre editanything sparkta2

GitHub data

Plenty of the data a do-file needs now lives in a GitHub repository rather than a
package. data() fetches it. Name the files you want:

. usepackage, data("datasets/gdp") files("data/gdp.csv") useit

or name none and usepackage lists every .dta, .csv,
.tsv, .xlsx and .txt it can see and asks before downloading in
bulk. useit loads the result when exactly one file was fetched, choosing
use, import delimited or import excel by extension.

Two things this handles that a hand-written copy does not.

Branch guessing. Older repositories are on master, newer ones on
main; usepackage finds whichever is live.

Git LFS. A repository that tracks large files with Git LFS serves a
130-byte text pointer from the raw endpoint instead of the data, so a plain
copy appears to succeed and leaves you with a file Stata cannot read
(not Stata format, r(610)). usepackage notices the pointer and
silently re-fetches from GitHub's media endpoint, reporting that it did so.

Pairing with require (version pinning)

usepackage answers "is it here, and if not where does it live?". It
does not check versions. If you need that -- and for reproducible
research you do -- pair it with require by Sergio Correia and
Matthew P. Seay (Stata Journal 24(4):599-613, 2024;
pr0081,
also on SSC).

The two solve different halves of one problem and compose cleanly:

. usepackage estout coefplot reghdfe ftools, noconfirm

. require reghdfe >= 6.0.0, install

. require ftools >= 2.49.0, install

usepackage gets the packages there whatever they happen to be called and
wherever they live; require then asserts that the versions are ones your
results were produced under. That second step matters more than it sounds:
newer releases of estimation commands can change point estimates or standard
errors, so "installed" is not the same as "the same".

Use require's requirements-file form when a project has several do-files:

. require using "requirements.txt", install

and generate that file from what you currently have with
require, list save. Reach for usepackage first when you do not yet
know what is missing or where it comes from, and for require to hold a
known-good set steady afterwards.

Division of labour, briefly:

usepackage discovery - SSC, SJ/STB catalogue, GitHub; command-to-package
resolution; ancillary files; data

require enforcement - minimum or exact versions, semantic-version
parsing, requirements files, required Stata version

github by E. F. Haghish (Stata Journal 20(4):931-951, 2020) is the
third relative: it is the deeper tool for GitHub-hosted package lifecycle
(release tags, author-declared dependency chains, update checks, uninstall,
building packages). It works entirely through the GitHub API, including the
code-search endpoint, so it is rate-limited in a way usepackage's
raw-endpoint probing is not. Prefer github when you want a tagged release
or an author's declared dependencies; prefer usepackage for one mixed list
across SSC, the Journal, and GitHub, or when you need data.

Remarks

A personal copy can mask a package. An .ado sitting in your PERSONAL
directory wins over anything net install writes to PLUS, so you can install
a package and still run the old code. When the command it finds is a PERSONAL
copy, usepackage says so instead of quietly reporting success.

Searching is chatty in a log. Finding non-SSC packages means calling
net search, which writes its catalogue to any open
log even when run quietly. Nothing is printed to the Results window, but expect
the raw catalogue in a log file. (In version 1 this output could not be
suppressed at all.)

usepackage only saves typing for more than one package. For a single known
package, ssc install is shorter.

Examples

Setup

. cap ado uninstall statplot

. cap ssc install usepackage

A list of packages, in one line -- the everyday use

. usepackage estout coefplot fre statplot

Check first, install nothing

. usepackage estout coefplot fre statplot, dryrun

Update packages you already have

. usepackage estout fre, update

A command that lives in a differently named package

. usepackage dropmiss

reports that dm89_2 ships dropmiss and asks before installing

. usepackage dropmiss, noconfirm

accepts that inferred match without asking

A misspelling, with nearest

. usepackage statplo, nearest

Skip the example datasets a package ships

. usepackage flowbca, noconfirm noancillary

Install from a known source, no searching

. usepackage dm89_2, from("http://www.stata-journal.com/software/sj15-4")

A package on GitHub

. usepackage applyvarlabels, github("ericabooth/applyvarlabels-stata-public")

probes the layout, installs, and fetches the 2 ancillary example files

. usepackage sparkta2, github("texas-2036/sparkta2-stata-public")

its D3 and TopoJSON assets are ancillary, so they come too

Search a whole GitHub account instead of naming the repository

. usepackage editanything, github("texas-2036")

lists the account's repos, narrows by name, installs the one that ships it

What Stata packages does an account ship?

. usepackage, github("texas-2036")

. usepackage *, github("ericabooth")

A pasted repository URL, in any of its usual shapes

. usepackage editanything, github("https://github.com/texas-2036/EditAnything-stata-public")

. usepackage editanything, github("https://github.com/texas-2036/EditAnything-stata-public/tree/main")

Set your own accounts once, then forget about GitHub

. global usepackage_github "ericabooth texas-2036" // in profile.do

. usepackage editanything

not on SSC or in the catalogue, so those accounts are searched

One list spanning SSC, the Stata Journal, and your own repositories

. usepackage fre dropmiss editanything sparkta2, noconfirm

Install, then pin the versions with require

. usepackage estout coefplot reghdfe ftools, noconfirm

. require reghdfe >= 6.0.0, install

see Pairing with require

One data file from GitHub, loaded

. usepackage, data("datasets/gdp") files("data/gdp.csv") useit

. list in 1/5

A Stata dataset held under Git LFS

. usepackage, data("scunning1975/mixtape") files("nsw_mixtape.dta") useit

the raw endpoint serves an LFS pointer; usepackage re-fetches the real file

A repository still on master

. usepackage, data("fivethirtyeight/data") files("airline-safety/airline-safety.csv") useit

Several data files into a subdirectory

. usepackage, data("scunning1975/mixtape") files("nsw_mixtape.dta cps_mixtape.dta") into("data")

See what data a repository holds before taking any

. usepackage, data("datasets/population") dryrun

Packages and data in one call

. usepackage estout coefplot, data("datasets/gdp") files("data/gdp.csv")

Audit a do-file before sending it out

. usepackage, scan("analysis.do")

lists the commands a collaborator would be missing

What a shared do-file might open with

. usepackage estout coefplot fre reghdfe, noconfirm

Stored results

usepackage stores the following in r():

Scalars

r(nreq) packages requested

r(nok) packages installed

r(nskip) packages already present

r(ndefer) inferred matches left awaiting confirmation

r(nfail) packages not resolved

Macros

r(unresolved) names that could not be found

r(deferred) names whose match needs confirming

So a do-file can stop rather than fail obscurely later:

. usepackage estout coefplot reghdfe, noconfirm

. if r(nfail) > 0 {

. di as error "missing: `r(unresolved)'"

. exit 601

. }

Author

Eric A. Booth, Sr Researcher, Texas 2036

eric.a.booth@gmail.com

github.com/ericabooth/usepackage-stata-public

Version 1.0.0 (2011) was written at the Public Policy Research Institute, Texas
A&M University.

Also see

Help: [R] net, [R] ssc,
search, findit, adoupdate

Related community commands: require (Correia and Seay, SJ 24(4)) for
version pinning - see Pairing with require;
github (Haghish, SJ 20(4)) for GitHub release tags and
author-declared dependencies.