Linking Python and C++ with Boost.python
Introduction to Boost
Boost is a project to create open-source libraries for C++. There are a lot of nice tools available through Boost, one of which is Boost.python. Boost.Python provides seamless interoperability between C++ and Python. I have found it to be an extremely useful tool for scientific programming. Parts of a program that require more flexibility than speed can be written in Python, and critical portions can be coded in C++.
Tutorials and Examples
Unfortunately, the Boost.Python documentation is not written for beginners, and there is not a lot of help on other web sites. The mailing list is great, but a good mailing list does not replace good introductory documentation.
Hello World
Here is the “hello world” example from the Boost.python tutorial. I found that attempting to configure the Boost.jam build system is far more confusing than using GNU make to build the examples. The following presentation should be much easier to understand. All files to build this example can be found in the Shocksolution_Examples repo on GitHub. Save the following as hello_ext.C [code language=“cpp”]char const* greet() { return “hello, world”; } #include <boost/python.hpp> BOOST_PYTHON_MODULE(hello_ext) { using namespace boost::python; def(“greet”, greet); }[/code]
Save the following as Makefile:
# location of the Python header files
PYTHON_VERSION = 2.7
PYTHON_INCLUDE = /usr/include/python$(PYTHON_VERSION)
# location of the Boost Python include files and library
BOOST_INC = /usr/include
BOOST_LIB = /usr/lib
# compile mesh classes
TARGET = hello_ext
$(TARGET).so: $(TARGET).o
g++ -shared -Wl,--export-dynamic $(TARGET).o -L$(BOOST_LIB) -lboost_python-$(PYTHON_VERSION) -L/usr/lib/python$(PYTHON_VERSION)/config -lpython$(PYTHON_VERSION) -o $(TARGET).so
$(TARGET).o: $(TARGET).C
g++ -I$(PYTHON_INCLUDE) -I$(BOOST_INC) -fPIC -c $(TARGET).CSave the following as test_hello.py [code language=“python”]import hello_ext print(hello_ext.greet())[/code] That’s it.
Other Examples
Extractor class exampleUsing a raw C++ data structure in Python* Mixing Python types in a Boost.Python list
Comments
Comment #1 by Configuring Boost::Python and Hello Boost « Paranoid Android
Configuring Boost::Python and Hello Boost « Paranoid Android - Jun 1, 2012
[…] I have found this link very helpful in making hello world program using Boost::Python. https://shocksolution.com/python-basics-tutorials-and-examples/linking-python-and-c-with-boostpyt… […]
Comment #2 by Yati Sagade
Yati Sagade - Feb 4, 2013
You saved me from the horrible hellhole this BoostJam is. It almost feels like it was crafted not to be used by anyone but the core developers. Thanks :)
Comment #3 by Craig
Craig - Feb 4, 2013
Yati, thank you for letting me know that this post was helpful!
Comment #4 by Pawel
Pawel - Feb 4, 2013
Thanks!!! So thankful for sharing how to do this.
Comment #5 by Ross
Ross - Feb 4, 2013
Craig, I expect you will get lots of traffic with your solution. I’ve been trying to get your files to compile, but I’m having a few Makefile issues. After editing with Nano to confirm tabs rather than spaces and converting to unix lifefeeds, I’m getting an error: make: hello_ext.o: Command not found. Any idea why make is viewing $(TARGET).o as a command?
Comment #6 by Craig
Craig - Feb 4, 2013
Ross, the formatting of the Makefile in this post was causing a lot of problems. I have refomatted the Makefile in the post and added all necessary files for the example to my repo on GitHub (link is near the top of the post). Also, the version of Boost on my workstation now has separate library files for each Python version, so I modified the Makefile accordingly. Let me know if there are any further problems.
Comment #7 by Ross
Ross - Mar 5, 2013
Craig, brilliant work. After a few mods to my own python and boost lib paths, and checking the whitespace/tabs formatting, your Makefile worked like a charm. With no disrespect to the bjam fellows, I worked on bjam until I was about to pass out and realized I could probably build using good-old-fashioned make (with a little help). That’s when a search took me to your site. Thanks for unblocking the road.
Comment #8 by Jake
Jake - Sep 2, 2013
I was just about to give up on boost and handle my c++ with python “subprocess”. You saved my day! Thanks.
Comment #9 by Bharat
Bharat - Oct 5, 2013
I am getting error /usr/local/include/boost/python/detail/wrap_python.hpp:50:23: fatal error: pyconfig.h: No such file or directory # include Any idea what could be the problem here?
Comment #10 by Craig
Craig - Oct 5, 2013
There is probably a problem with the configuration of your include paths. I suspect that the compiler cannot find the source directory with the Python header files, so you may need to set an environment variable or use a command-line flag to tell it where to find the header files.
Comment #11 by rseed42
rseed42 - Feb 6, 2014
Thanks, dude
Comment #12 by Menaka
Menaka - Mar 3, 2014
hi! I get this error when i try to make it. g++ -shared -Wl,–export-dynamic hello_ext.o -L/usr/lib -lboost_python-2.7 -L/usr/lib/python2.7/config -lpython2.7 -o hello_ext.so /usr/bin/ld: cannot find -lboost_python-2.7 collect2: ld returned 1 exit status make: *** [hello_ext.so] Error 1 please help me! thanks in advance.
Comment #13 by Craig
Craig - Mar 4, 2014
The linker cannot find the library called boost_python-2.7. You should find the path to this library on your system and provide that path to the linker with a -L flag as you have done with the other library paths. If that library doesn’t exist, it may need to be installed, or you may have specified its name incorrectly.
Comment #14 by Yu Lu
Yu Lu - Apr 4, 2014
Thanks for the post, very helpful and solved my problem
Comment #15 by Nima Hazar
Nima Hazar - May 1, 2014
in the Makefile try -lboost_python instead of -lboost_python-$(PYTHON_VERSION) In my case the boost_python library name does not have the python version as a suffix.
Comment #16 by ITBEE.net
ITBEE.net - Jun 1, 2014
Very good post. Thanks a lot. noBJAM solution ftw!
Comment #17 by cclloyd
cclloyd - Mar 3, 2015
I get an error with –export-dynamic being an unknown option.
Comment #18 by Craig
Craig - Mar 3, 2015
Make sure your Makefile is identical to the one I posted on GitHub. Note that spaces and tabs are critical! The –export-dynamic option is a linker (LD) flag, NOT a compiler (GCC) flag. You pass flags to the linker by giving GCC the flag “-Wl,” followed by the desired linker flag. There cannot be a space between the comma and the linker flag.
Comment #19 by Akim
Akim - Mar 2, 2015
You should rather call python-config (with –ldflags, –libs etc.) to get the flags to use.
Comment #20 by Farzad
Farzad - Jan 4, 2016
Thanks! This did the trick for me.
Comment #21 by saravanakumar velayutham
saravanakumar velayutham - Mar 1, 2016
Good post .. Made my day
Comment #22 by TC
TC - Apr 4, 2016
This is great, thank you for taking the time to make a walk through. The Boost documentation is cryptic for those attempting to use the libraries for the first time. I’ve made it past a few of the common errors that I’m seeing on this thread and elsewhere, but I’m getting this error: g++ -I/Users/tomconlin/anaconda/pkgs/python-2.7.11-0/include/python2.7 -I/usr/include -fPIC -c hello_ext.C g++ -shared -Wl,–export-dynamic hello_ext.o -L/usr/lib -lboost_python -L/usr/lib/python2.7/config -lpython2.7 -o hello_ext.so ld: unknown option: –export-dynamic clang: error: linker command failed with exit code 1 (use -v to see invocation) make: *** [hello_ext.so] Error 1 Has anyone seen anything like this before? Any insights would be greatly appreciated!! Thanks again for the tutorial, simple and to the point!
Comment #23 by HARIHARAN RAGOTHAMAN
HARIHARAN RAGOTHAMAN - Jul 1, 2016
I am getting the following. It would be great if you could tell me what happens here. ImportError: /scratch/Python_stuff/Python_Boost/hello_ext.so: undefined symbol: _ZN5boost6python6detail11init_mod uleEPKcPFvvE
Comment #24 by Craig
Craig - Jul 1, 2016
I haven’t worked with Python and Boost in a long time, so I can’t help you.
Comment #25 by Alam
Alam - Jul 4, 2016
Hi I downloaded all the files and tried to run the python file. But it is giving me following error: ImportError: No module named hello_ext I am not sure whether Boost Python is installed on my system. I tried to install it using BoostPython website but it did not work. Can someone tell me about the installtion of boost python library for python 2.7? It would be great if you could also help me in troublehooting this error. Thanks in anticipation.
Comment #26 by ArunV
ArunV - Sep 0, 2016
I had the same issue with “ImportError” (working on the new windows subsystem for Linux for Windows 10). It was related to not linking the correct library name (boost_python-py27 not boost_python-2.7 per the Makefile example above) and the fact that my boost-python link path was set incorrectly (ie not -L/usr/lib but -L/usr/lib/x86_64-linux-gnu). Hope this helps Hari and Alam…
Comment #27 by magneto_without_the_powers
magneto_without_the_powers - Jun 0, 2017
Thanks! .. I don’t know what BJam is and I’m not interested in learning it.
Comment #28 by Prakash
Prakash - Aug 3, 2017
Hi, I tried running your files in git. But its giving me an error. ImportError: No module named hello_ext. I have boost installed on my system and I am trying to run this program on Windows 7. Any help will be appreciated
Comment #29 by Craig
Craig - Aug 3, 2017
Problems like this are very specific to the way that libraries are installed and configured on your particular system, so I can’t help with this type of problem. Also, I have never done this on a Windows system.
Comment #30 by Gary
Gary - Aug 4, 2017
I am getting the following error. /usr/bin/ld: cannot find -lboost_python-2.7
Comment #31 by Hootan
Hootan - Aug 5, 2017
WOW, Thank you big time I cant believe that it says hello :V It’s 3 days that I’m trying to make the boost_python works, I was giving up on it !
Comment #32 by skulumani
skulumani - Feb 5, 2018
Thank you for this great blog post. It was a huge help in getting my build environment setup. It took the better part of a day but I at least got “hello world” from C++ into Python.
Comment #33 by Israel.Cma
Israel.Cma - Mar 5, 2018
In clang it should be replaced by -Wl,-export_dynamic
Comment #34 by Robert
Robert - Aug 3, 2018
On Ubuntu 14.04LTS, I had to change the descriptor for boost_python and remove the following: -L/usr/lib/python$(PYTHON_VERSION)/config -lpython$(PYTHON_VERSION) as my installation on Ubuntu 14.04LTS has no such config directory The result that works for me looks like this (python3.4 and my source has .cpp extension): $(TARGET).so: $(TARGET).o g++ -shared -Wl,–export-dynamic $(TARGET).o -L$(BOOST_LIB) -lboost_python-py34 -o $(TARGET).so $(TARGET).o: $(TARGET).cpp g++ -I$(PYTHON_INCLUDE) -I$(BOOST_INC) -fPIC -c $(TARGET).cpp Thank you for the post, was getting frustrated with bjam.
Comment #35 by craig
craig - Sep 6, 2018
Robert: thank you for the update!
Comment #36 by D
D - Mar 6, 2022
Its an old tutorial, and it seems to not wor with current boost python any more. However the official documentation has not updated there hellow world either and now im stuck with either: g++ -I/usr/include/python3.9 -I/usr/include -fPIC -c hello_ext.C In file included from /usr/include/boost/smart_ptr/detail/sp_thread_sleep.hpp:22, from /usr/include/boost/smart_ptr/detail/yield_k.hpp:23, from /usr/include/boost/smart_ptr/detail/spinlock_gcc_atomic.hpp:14, from /usr/include/boost/smart_ptr/detail/spinlock.hpp:42, from /usr/include/boost/smart_ptr/detail/spinlock_pool.hpp:25, from /usr/include/boost/smart_ptr/shared_ptr.hpp:29, from /usr/include/boost/shared_ptr.hpp:17, from /usr/include/boost/python/converter/shared_ptr_to_python.hpp:12, from /usr/include/boost/python/converter/arg_to_python.hpp:15, from /usr/include/boost/python/call.hpp:15, from /usr/include/boost/python/object_core.hpp:14, from /usr/include/boost/python/args.hpp:22, from /usr/include/boost/python.hpp:11, from hello_ext.C:5: /usr/include/boost/bind.hpp:36:1: note: ‘#pragma message: The practice of declaring the Bind placeholders (_1, _2, …) in the global namespace is deprecated. Please use + using namespace boost::placeholders, or define BOOST_BIND_GLOBAL_PLACEHOLDERS to retain the current behavior.’ 36 | BOOST_PRAGMA_MESSAGE( | ^~~~~~~~~~~~~~~~~~~~ /usr/include/boost/detail/iterator.hpp:13:1: note: ‘#pragma message: This header is deprecated. Use instead.’ 13 | BOOST_HEADER_DEPRECATED("") | ^~~~~~~~~~~~~~~~~~~~~~~ g++ -shared -Wl,–export-dynamic hello_ext.o -L/usr/lib -lboost_python-3.9 -L/usr/lib/python3.9/config -lpython3.9 -o hello_ext.so /usr/bin/ld: cannot find -lboost_python-3.9 collect2: error: ld returned 1 exit status make: *** [Makefile:10: hello_ext.so] Error 1 and if I follow the advice of using instead of the error changes to: g++ -I/usr/include/python3.9 -I/usr/include -fPIC -c hello_ext.C hello_ext.C:6:20: error: expected constructor, destructor, or type conversion before ‘(’ token 6 | BOOST_PYTHON_MODULE(hello_ext) | ^ make: *** [Makefile:12: hello_ext.o] Error 1 what is less verbose but doesnt work either :(
Comment #37 by craig
craig - Mar 3, 2022
You are correct-this is a very old tutorial. I haven’t used Boost.python in at least 10 years. From its web page, I can’t tell if it’s even maintained anymore. Good luck!
Comment #38 by user-899446
user-899446 - Jun 1, 2025
awesome