# Building and Installing &SCons;

This chapter will take you through the basic steps of installing &SCons; on your system, and building &SCons; if you don't have a pre-built package available (or simply prefer the flexibility of building it yourself). Before that, however, this chapter will also describe the basic steps involved in installing Python on your system, in case that is necessary. Fortunately, both &SCons; and Python are very easy to install on almost any system, and Python already comes installed on many systems.

## Installing Python

Because &SCons; is written in Python, you need to have Python installed on your system to use &SCons;. Before you try to install Python, you should check to see if Python is already available on your system by typing `python -V` (capital 'V') or `python --version` at your system's command-line prompt. For Linux/Unix/MacOS/BSD type systems this looks like:

    $ python -V
    Python 3.7.1

Note to Windows users: there are a number of different ways Python can be installed or invoked on Windows, it is beyond the scope of this guide to unravel all of them. Many will have an additional program called the Python launcher (described, somewhat technically, in PEP 397): try using the command name `py` instead of `python`, if that is not available drop back to trying `python`.

    C:\>py -V
    Python 3.7.1

If Python is not installed on your system, or is not findable in the current search path, you will see an error message stating something like `"command not found"` (on UNIX or Linux) or `"'python' is not recognized as an internal or external command, operable progam or batch file"` (on Windows `cmd`). In that case, you need to either install Python or fix the search path before you can install &SCons;.

The canonical location for downloading Python from Python's own website is: https://www.python.org/download. There are useful system-specific entries on setup and usage to be found at: https://docs.python.org/3/using

For Linux systems, Python is almost certainly available as a supported package, possibly installed by default; this is often preferred over installing by other means, and is easier than installing from source code. Many such systems have separate packages for Python 2 and Python 3 - make sure the Python 3 package is installed, as the latest &SCons; requires it. Building from source may still be a useful option if you need a version that is not offered by the distribution you are using.

&SCons; will work with Python 3.5 or later. If you need to install Python and have a choice, we recommend using the most recent Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;.

## Installing &SCons;

The canonical way to install &SCons; is from the Python Package Index (PyPi):

    % python -m pip install scons

If you prefer not to install to the Python system location, or do not have privileges to do so, you can add a flag to install to a location specific to your own account:

    % python -m pip install --user scons

For those users using Anaconda or Miniconda, use the `conda` installer instead, so the &scons; install location will match the version of Python that system will be using. For example:

    % conda install -c conda-forge scons

&SCons; comes pre-packaged for installation on many Linux systems. Check your package installation system to see if there is an &SCons; package available. Many people prefer to install distribution-native packages if available, as they provide a central point for management and updating. During the still-ongoing Python 2 to 3 transition, some distributions may still have two &SCons; packages available, one which uses Python 2 and one which uses Python 3. Since the latest &scons; only runs on Python 3, to get the current version you should choose the Python 3 package.

If you need a specific version of &SCons; that is different from the package available, pip has a version option or you can follow the instructions in the next section.

## Building and Installing &SCons; on Any System

If a pre-built &SCons; package is not available for your system, and installing using pip is not suitable, then you can still easily build and install &SCons; using the native Python setuptools package.

The first step is to download either the `scons-&buildversion;.tar.gz` or `scons-&buildversion;.zip`, which are available from the SCons download page at https://scons.org/pages/download.html.

Unpack the archive you downloaded, using a utility like tar on Linux or UNIX, or WinZip on Windows. This will create a directory called `scons-&buildversion;`, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands:

    # cd scons-&buildversion;
    # python setup.py install

This will build &SCons;, install the &scons; script in the python which is used to run the setup.py's scripts directory (`/usr/local/bin` or `C:\Python37\Scripts`), and will install the &SCons; build engine in the corresponding library directory for the python used (`/usr/local/lib/scons` or `C:\Python37\scons`). Because these are system directories, you may need root (on Linux or UNIX) or Administrator (on Windows) privileges to install &SCons; like this.

### Building and Installing Multiple Versions of &SCons; Side-by-Side

The &SCons; `setup.py` script has some extensions that support easy installation of multiple versions of &SCons; in side-by-side locations. This makes it easier to download and experiment with different versions of &SCons; before moving your official build process to a new version, for example.

To install &SCons; in a version-specific location, add the `--version-lib` option when you call `setup.py`:

    # python setup.py install --version-lib

This will install the &SCons; build engine in the `/usr/lib/scons-&buildversion;` or `C:\Python27\scons-&buildversion;` directory, for example.

If you use the `--version-lib` option the first time you install &SCons;, you do not need to specify it each time you install a new version. The &SCons; `setup.py` script will detect the version-specific directory name(s) and assume you want to install all versions in version-specific directories. You can override that assumption in the future by explicitly specifying the `--standalone-lib` option.

### Installing &SCons; in Other Locations

You can install &SCons; in locations other than the default by specifying the `--prefix=` option:

    # python setup.py install --prefix=/opt/scons

This would install the scons script in `/opt/scons/bin` and the build engine in `/opt/scons/lib/scons`,

Note that you can specify both the `--prefix=` and the `--version-lib` options at the same type, in which case `setup.py` will install the build engine in a version-specific directory relative to the specified prefix. Adding `--version-lib` to the above example would install the build engine in `/opt/scons/lib/scons-&buildversion;`.

### Building and Installing &SCons; Without Administrative Privileges

If you don't have the right privileges to install &SCons; in a system location, simply use the `--prefix=` option to install it in a location of your choosing. For example, to install &SCons; in appropriate locations relative to the user's `$HOME` directory, the &scons; script in `$HOME/bin` and the build engine in `$HOME/lib/scons`, simply type:

    $ python setup.py install --prefix=$HOME

You may, of course, specify any other location you prefer, and may use the `--version-lib` option if you would like to install version-specific directories relative to the specified prefix.

This can also be used to experiment with a newer version of &SCons; than the one installed in your system locations. Of course, the location in which you install the newer version of the &scons; script (`$HOME/bin` in the above example) must be configured in your &PATH; variable before the directory containing the system-installed version of the &scons; script.