Note: This FAQ is based on a
I have a certain version of Stata and have come across a user-written
program that is apparently written for a later version of Stata. What
are my options?
||User-written programs and Stata version
||Nicholas J. Cox, Durham University, UK
February 2009; updated July 2011
Suppose you have Stata 10.1. You may in fact have an earlier version, or
indeed a later version, as you read this. You should be able to relate to
examples here as long as you are clear that there are three possible
situations: a Stata program may be written for the same version of Stata
that you have, an earlier version, or a later version. It is the last
situation that is the focus here.
2. The different meanings of version
You need to distinguish the four meanings of the word “version”
in discussions of this and related problems. In programming jargon, the word
is heavily overloaded.
2a. The version of Stata you are using
Any copy of Stata you run has a version. Stata itself will tell you the
version in several ways, such as in the GUI when you start a session or if
c(version). (If you have a really old version of Stata, some of these
methods may not work.)
The version of Stata you are using is always displayed, such
as 12, 11.2, 11.1, 11, etc. If you are not using the most recent version of
Stata, the version you are using imposes limits on what you can do with
2b. The programmer’s personal version number
Most Stata commands are defined by programs written in Stata and defined by
ado-files. The exceptions are part of the executable and do not come under
this FAQ. Many programmers keep track of the history of their programs by
including a comment such as
*! version 3.10 20jan2009 Ben Jann
Usually, that comment is placed at or near the top of the ado-file. In
the example above, the comment appears at the top of estout, a
popular ado-file, as downloaded from SSC on 25 January 2009. The
programmer, Ben Jann, has his own version number for estout so that
he can keep track of which version is which. User-programmers often mimic a
style used by StataCorp and common throughout computing: the first
number marks major rewrites, and any following numbers mark minor changes.
The version number also can help users of any program keep track of which
version they are using and whether they need to update. For example, if you
have previously installed estout, then typing
will tell you which version you have installed.
This number also helps in dealing with bug reports. If you experience a
problem with a user-written program, then check that you have the most
recent version. Often a bug that bites you bit someone else first, and the
bug is fixed in a later version.
As stated above, the line starting with *! is a comment.
The initial * is what makes it a comment.
Comments are generally ignored by Stata. However, the following !
makes that comment special, because the which command looks for lines
beginning *! and echoes them to the Results window. Thus if you want
to know which version of xyzzy you are using, then all you have to do
is type which xyzzy, and you will see
. which xyzzy
*! version 3.10 20jan2009 Ben Jann
The above works whether xyzzy is a user-written command or an
official Stata command.
Some programmers do not use the *! version number. You will find
Stata’s own commands and most of the heavily used user-written
commands generally do use it, but this is mainly an issue of style.
However interesting or informative you find this, remember that the
*! version number used personally by the programmer has no
implications whatsoever for whether your version of Stata is modern enough
to use the program.
2c. The version declared within a program
The easy way to find out whether you can use a program is just to try it.
Either the program will work or you might see something like
this is version 10.1 of Stata; it cannot run version 10.2 programs.
A free update to version 10.2 is available; type update and follow the
instructions, or visit http://www.stata.com/support/updates. If you are
not connected to the Internet, you can contact StataCorp to obtain the
Or you might see
. xyzzy ...
this is version 8.2 of Stata; it cannot run version 9.0 programs.
You can purchase the latest version of Stata by visiting
Let me show you how this works. We are going to have to look
inside the program to do so. The easy way to do that is to type
. viewsource name_of_ado_file
A Viewer window will display the source code.
For instance, say you have installed estout from SSC. If you type
. viewsource estout.ado
you will see in the Viewer window something like
*! version 3.10 20jan2009 Ben Jann
program define estout, rclass
Look for the version statement—not to be confused with the
*! comment. The version statement is usually found near the
top of the program, after the
estout is declared to be version 8.2, meaning it requires
Stata 8.2 or a more recent version to run.
Most programs include at least one version statement. The
first—which is often the only one—is usually found at or near
the top of the program definition.
Often programs call other programs, and sometimes those programs call yet
other programs. When that happens, the highest version number is that which
bites. Thus if foobar, which declares itself to require version
8.2, calls frogtoadandnewt, which declares itself to require
version 9, then you need at least Stata version 9 to run
Some programmers write branching code within their programs that detects the
version of Stata you have and calls other code accordingly. For example, if
you have Stata 9 or above, then a clever program may call fast and efficient
Mata routines to do some work; if you do not have Stata 9, then the program
calls code that will do the same job, albeit more slowly. In this way, it is
possible that a program containing some code that would not run on your
version of Stata is usable by you, because the program itself is smart
enough to work around that limitation.
Precisely what version does is too complicated to explain in full
detail here. There is no substitute for careful reading of the documentation
for version. But you are warned against a surprisingly common
misconception: that the version command is a time machine. It
emphatically is not a time machine. version cannot be used to make an
old Stata behave like a newer Stata.
What version does is set the clock back to make a more modern Stata
behave like an older version or, at least, behave like an older version where
that older behavior is important.
Here is the main idea. Suppose you have Stata 12, and a program includes the
Your copy of Stata 12 does not remove all the improvements and new
features of Stata 12. What the version 8.2 statement does, in any
case where there is a conflict between what was in Stata 8.2 and what is now
in Stata 12, is to use the Stata 8.2 interpretation.
It is difficult (impossible, really) for you to be certain that what you
have within Stata 12 will work exactly as it would in Stata 8.2 unless you
test it by running a physical copy of Stata 8.2. You might be exploiting a new,
nonconflicting feature introduced since Stata 8.2 without realizing it.
Some users tend to look at version 8.2 at the top of a program and
say, “Oh, this will work with Stata 8.2”. That statement is
necessarily true if the program was written only on Stata 8.2.
version is about forward compatibility, not backward. What is true,
and all that is guaranteed to be true, is that a program written on Stata
8.2, with a version 8.2 statement at the top, will continue to work
properly with future versions of Stata.
By the way, on occasion there can be good and subtle reasons for omitting a
version statement. But, more commonly, a program (or a do-file for that
matter) would benefit from a version statement.
If there is no version statement within a program, then that omitted
statement can have no bite. But keep on reading.
2d. The version needed within a program
Programmers can be a little cavalier about what they say in any
version statement included in their programs. There are two
- Some programmers write the version of Stata they are using as the
version needed by their programs. Their thinking is, “I
know that this program runs fine on this version of Stata, because that
is the version on which it is being developed and tested by me. I am not
going to commit myself to any backward compatibility.” In
particular, StataCorp programmers think and act this way.
- Other programmers write down an earlier version of Stata as the
version needed by their program. Their thinking is, “I
believe that this program does require at least that version of Stata,
because it needs certain features introduced then.” For example,
a program may require the current Stata graphics introduced in Stata 8
or a particular version of the
introduced in another version of Stata.
In either case, note that many Stata programmers either do not
have older versions of Stata on their machines or lack the time and
inclination to test whether their program would run successfully on an
older version. So any version statement given explicitly within a
program may not be the exact version of Stata that the program needs.
Also it is not wrong to declare a version statement either less than
or more than what is really needed, so long as the version number is
not greater than the version of Stata being written for.
3. Looking inside a program
You may want to look inside a program to
see what version is declared. Even if the documentation includes
information on the Stata version required, checking on the facts will do no
harm. The documentation can be wrong, most commonly because the
documentation itself is out of date. In any case, what the program requires
is all that matters. Stata pays no attention to anything said in the help
file or anywhere other than the program itself.
to look inside a program was mentioned earlier; you may also find it helpful to
type a program may be enough. (With
aware of the subcommand ssc type.)
Now the question can be answered directly.
If you have Stata 9, and the foobar command appears to require Stata
9.2 and the bazz command appears to require Stata 10.1, what can you
If your Stata version differs by 1 or more from what is required, you can
purchase an upgrade to the current version from StataCorp.
If your Stata version has the same initial integer as what is required, you
your Stata for free over the web. For example, you can update from
Stata 10 to Stata 10.1 or from Stata 11 to Stata 11.2; just type
update. You cannot update for free from (say) Stata 11.2 to
Stata 12. That requires an upgrade, as described just above.
4c. Look for older versions or older alternatives
An older version of a program may be found. For example,
the Stata Journal
and the Stata Technical Bulletin
archives retain all previous versions of any programs published therein;
some packages in the SSC archives include versions for older Stata programs;
some users’ websites allow you to download different versions of a
program according to your version of Stata. Commonly, older versions are
frozen as they were and are not updated, even when it is possible.
One common, but not universal, convention is that names like foobar7,
foobar8, and foobar9 may signal versions of foobar for
Stata 7, 8, or 9. The documentation will usually make this clear, but, if in
doubt, you can look inside each program, as above. Another common convention
is that foobar2 and foobar3 merely mark successive
versions of foobar, but as Stata ages the chance of these two
conventions clashing diminishes.
Similarly, there can be older alternatives. Using
(possibly with the historical option), using
asking on Statalist can help here, perhaps by implying that no older
4d. Change the program
You can copy the program in question and try to change it so that it works
under your version of Stata. This process will vary from being trivially
easy to being essentially impossible, depending on how many
newer features any program requires. The difficulty also
depends on your knowledge of Stata.
At the easiest, it may simply be that the version statement specifies
a version later than really needed. Thus, if you edit version 12 to
version 11, then you may find that a program works under Stata 11.
But watch out:
- You now take full responsibility for what you have done, while
etiquette still requires that you give full credit and respect to previous
authors. Most program authors take mild to strong exception to others
changing their program and then asking why it no longer works.
- You are advised to change the name of the program. For example, if your
initials are XYZ, you might change foobar to foobar_xyz.
Or if you adapt foobar to work on Stata 9, foobar9 is a
possible name. Running findit with a possible program name will
indicate any clashes of name with programs in the most accessible
sources. If you do not change the name, you can confuse yourself and
others you distribute the program to, even if you only use
the program within a restricted group. You will find it difficult to
keep track of which variation of the program you are running. And, if
you keep the same name, you run the risk that your version will get
overwritten, say, by an
Finally, you should not put your version in the public
domain where it can be confused with the original.
- Even if an edited program appears to work satisfactorily, that is not a
guarantee that your version produces identical results to the original.
- The original program authors will commonly
have little or no interest in rewriting a program to work on an
older version of Stata for you.
But often a program would require more drastic surgery to the extent that
your only real choices are to upgrade, update, or do without.
5. A note on help files
Stata 10 and later versions of Stata look first for help files with
extension .sthlp and second for help files with extension
.hlp. Conversely, Stata 9 and earlier versions know nothing about the
Thus if you managed to get a Stata 10 program working in Stata 9, then you would
normally be best advised to rename any .sthlp files to have
the .hlp extension.
The previous section implies that it is now good practice to
edit the help files to indicate what has been changed and who is now
responsible, namely, you.
David Elliott suggested, on Statalist, that an FAQ be written on this topic.
He, William Gould, Ben Jann, and Richard Williams made very helpful comments
on a draft.