bootstrap.py

This section provides detailed usage information for the bootstrap.py command.

Synopsis

python bootstrap.py [OPTIONS]

Description

bootstrap.py is an enhanced virtualenv bootstrap script generated by the mkbootstrap command. The script creates a virtualenv environment, installs additional packages and runs additional commands, as configured, in order to set up a development environment for the project to which it belongs.

Additional packages can be installed using either pip, easy_install or both. The list of packages to install, any customized command-line option defaults and the list of additional post-install commands to run are all configured in a related configuration file, usually called bootstrap.cfg.

Options

bootstrap.py accepts several command-line options that are described below. Most of the options are the same as virtualenv itself or a standard virtualenv bootstrap script, but some have been replaced, modified or added to enhance behaviour.

Note

All the options below can also be set in bootstrap.cfg.

Standard virtualenv Options

The following options are unchanged from their normal virtualenv behaviour.

--version

This option tells bootstrap.py to just show program’s version and then exit.

-h, --help

This option tells bootstrap.py to just show program usage information and then exit. It lists all the options described here along with simple descriptions.

-v, --verbose

Increase the verbosity of program output. This is the opposite of the -q option. The more times this option is repeated, the higher the verbosity level.

Note

The verbosity level is not currently passed on to pip or easy_install.

-q, --quiet

Decrease verbosity of the program output. This is the opposite of the -v option. The more times this option is repeated, the lower the verbosity level.

Note

The verbosity level is not currently passed on to pip or easy_install.

-p PYTHON_EXE, --python PYTHON_EXE

Use this options to specify the Python interpreter to use, e.g., --python=python2.5 will use the python2.5 interpreter to create the new environment. The default is the interpreter used to run bootstrap.py.

--clear

Use this option to clear out the lib directory of any files from previous runs of bootstrap.py.

Note

According to the virtualenv source code, this option does not clear out the bin or any other directories, however, despite what is implied by the message provided by in --help option.

--system-site-packages

By default virtualenv configures the virtual environment to not include access to the system’s global site-packages directory. Use this option to reverse that choice and give access to the global site-packages directory to the virtual environment.

--relocatable

Use this option to make an EXISTING virtualenv environment relocatable. This option fixes up scripts and makes all .pth files, making paths relative.

Note

Do not use this option the first time running bootstrap.py. Call bootstrap.py a second time with this option, to achieve the desired result.

Warning

The authors of everyapp.bootstrap have not tried using this option in the context of bootstrap.py. YMMV.

--extra-search-dir SEARCH_DIRS

This options sets the directory in which to look for setuptools/distribute/pip distributions. You can add any number of additional --extra-search-dir paths. By default the latest distributions are downloaded from PyPI.

--never-download

Force virtualenv to never download anything from the network. Instead, it will fail if local distributions of setuptools/distribute/pip are not present. You can combine this option with the --extra-search-dir to set the location of the local distributions to install.

--prompt PROMPT

Use this option to give an alternative prompt prefix for tghe virtual environment.

Customized Options

The following options have been added or customized by everyapp.bootstrap to replace some virtualenv options and add additional functionality.

--setuptools

This is the opposite of the virtualenv --distribute option. By default bootstrap.py enables the --distribute option, which tells virtualenv to install distribute instead of setuptools in the virtual environment. Use this option to reverse that choice so that setuptools is installed instead.

--zip-setuptools

This is the opposite of the virtualenv --unzip-setuptools option. By default bootstrap.py enables the --unzip-setuptools option, which tells virtualenv to unzip the distribute or setuptools EGG in site-packages instead of leaving it as a compressed EGG file. Use this option to reverse that choice so that distribute or setuptools is left compressed.

--pip-install-options OPTIONS

bootstrap.py can be configured to install additional packages using pip. Use this option to set additional command line options for the pip install command. (Default is "".) Set this to the string of options just as you would give on the command-line.

--easy_install-options OPTIONS

bootstrap.py can be configured to install additional packages using easy_install. Use this option to set additional command line options for the easy_install command. (Default is "-Z", which tells easy_install to always unzip EGG files.) Set this to the string of options just as you would give on the command-line.

Examples

The simplest and most common usage is to just run bootstrap.py after a fresh checkout/clone of a project, in it’s root directory. For example:

cd /path/to/project/root
python bootstrap.py

This will create the virtualenv environment in the project root (i.e. the current directory), install additional packages and run additional commands, as configured, necessary to set up the development environment for the project.

Output

Running bootstrap.py will result in output in several phases. They are:

  1. Indication that a configuration file was found.
  2. The normal output from virtualenv creating the virtual environment.
  3. A list of the packages that will be installed using pip.
  4. The normal output of pip installing the packages.
  5. A list of the packages that will be installed using easy_install.
  6. The normal output of easy_install installing the packages.
  7. Indication that post-setup commands will be run.
  8. The normal output from running all the commands in sequence.

Files and Directories

bootstrap.cfg
The configuration file for bootstrap.py
bin or Scripts
The directory created by virtualenv for commands and executables.
lib/pythonX.Y or lib
The directory created by virtualenv for Python‘s standard library.
lib/pythonX.Y/site-packages or Lib\site-packages
The directory created by virtualenv for the virtual environment’s local packages.
lib64
A symlink created by virtualenv on 64-bit POSIX systems that points to the above-mentioned lib directory.

Environment Variables

Since bootstrap.py is basically a customized version of virtualenv, it uses all the same environment variables that are used by virtualenv.

See also

The virtualenv documentation for details.

Exit Status

0
Successful program execution
1
Operational error
2
Error parsing command-line options
3
  • Attempt to run virtualenv in an (obsolete) workingenv environment, or
  • Using a home directory that contains a space on Windows and not having pywin32 installed, or
  • The Python executable specified with --python does not exist
100
Error running Python interpreter due to it’s sys.prefix value not being what is expected
101
Attempt to run under a Python version less than 2.3
200
Error parsing the configuration file

Note

Other exit codes are possible as they can come from sub-processes like installing distribute, etc.