...one of the most highly
regarded and expertly designed C++ library projects in the
world. — Herb Sutter and Andrei
There is no need to “install Boost” in order to get started using Boost.Python. These instructions use Boost.Build projects, which will build those binaries as soon as they're needed. Your first tests may take a little longer while you wait for Boost.Python to build, but doing things this way will save you from worrying about build intricacies like which library binaries to use for a specific compiler configuration and figuring out the right compiler options to use yourself.
Of course it's possible to use other build systems to build Boost.Python and its extensions, but they are not officially supported by Boost. Moreover 99% of all “I can't build Boost.Python” problems come from trying to use another build system without first following these instructions.
If you want to use another system anyway, we suggest that you follow these
instructions, and then invoke
options to dump the build commands it executes to a file, so you can see what your alternate build system needs to do.
1. Get Boost; see sections 1 and 2 of the Boost Getting Started Guide.
2. Get the
bjam build driver.
See section 5 of the Boost Getting
3. cd into the
example/quickstart/ directory of your Boost.Python installation,
which contains a small example project.
from the example invocation from section 5 of the Boost Getting
Started Guide with “
to build all the test targets. Also add the argument “
--verbose-test” to see the output generated by
the tests when they are run. On Windows, your
invocation might look something like:
C:\\...\\quickstart> bjam toolset=msvc --verbose-test test
and on Unix variants, perhaps,
.../quickstart$ bjam toolset=gcc --verbose-test test
For the sake of concision, the rest of this guide will use unix-style forward slashes in pathnames instead of the backslashes with which Windows users may be more familiar. The forward slashes should work everywhere except in Command Prompt windows, where you should use backslashes.
If you followed this procedure successfully, you will have built an extension
and tested it by running a Python script called
You will also have built and run a simple application called
embedding that embeds python.
If you're seeing lots of compiler and/or linker error messages, it's probably
because Boost.Build is having trouble finding your Python installation.
You might want to pass the
--debug-configuration option to
bjam the first few times you invoke it,
to make sure that Boost.Build is correctly locating all the parts of your
Python installation. If it isn't, consider Configuring
Boost.Build as detailed below.
If you're still having trouble, Someone on one of the following mailing lists may be able to help:
Rejoice! If you're new to Boost.Python, at this point it might be a good idea to ignore build issues for a while and concentrate on learning the library by going through the Tutorial and perhaps some of the Reference Manual, trying out what you've learned about the API by modifying the quickstart project.
If you're content to keep your extension module forever in one source file
extending.cpp, inside your Boost.Python distribution,
and import it forever as
then you can stop here. However, it's likely that you will want to make
a few changes. There are a few things you can do without having to learn
Boost.Build in depth.
The project you just built is specified in two files in the current directory:
boost-build.jam, which tells
where it can find the interpreted code of the Boost build system, and
Jamroot, which describes
the targets you just built. These files are heavily commented, so they
should be easy to modify. Take care, however, to preserve whitespace. Punctuation
; will not be recognized
as intended by
it is not surrounded by whitespace.
You'll probably want to copy this project elsewhere so you can change it without modifying your Boost distribution. To do that, simply
a. copy the entire
example/quickstart/ directory into a new directory.
b. In the new copies of
Jamroot, locate the
relative path near the top of the file that is clearly marked by a comment,
and edit that path so that it refers to the same directory your Boost
distribution as it referred to when the file was in its original location
For example, if you moved the project from
/home/dave/my-project, you could change the first
and change the first path in
The names of additional source files involved in building your extension
module or embedding application can be listed in
embedding.cpp respectively. Just be sure to leave
whitespace around each filename:
… file1.cpp file2.cpp file3.cpp …
Naturally, if you want to change the name of a source file you can tell
Boost.Build about it by editing the name in
The name of the extension module is determined by two things:
To change the name of the extension module from
hello, you'd edit
python-extension extending : extending.cpp ;
python-extension hello : extending.cpp ;
and you'd edit extending.cpp, changing