Building a Python Project
What This Guide Covers #
Language versions and other build-environment specific information are in our reference pages:
Python builds are not available on the macOS environment.
Specifying Python versions #
Specify python versions using the
python key. As we update the Python build
images, aliases like
3.6 will point to different exact versions or patch
language: python python: - "2.6" - "2.7" - "3.3" - "3.4" - "3.5" - "3.5-dev" # 3.5 development branch - "3.6" - "3.6-dev" # 3.6 development branch # command to install dependencies install: - pip install -r requirements.txt # command to run tests script: - pytest
Python 3.7 and higher #
You’ll need to add
dist: xenial to your
.travis.yml file to use Python 3.7 and higher.
dist: xenial # required for Python >= 3.7 language: python python: - "3.7" - "3.7-dev" # 3.7 development branch - "3.8-dev" # 3.8 development branch - "nightly" # nightly build
Travis CI Uses Isolated virtualenvs #
The CI Environment uses separate virtualenv instances for each Python
version. This means that as soon as you specify
language: python in
.travis.yml your tests will run inside a virtualenv (without you having to explicitly create it).
System Python is not used and should not be relied on. If you need
to install Python packages, do it via pip and not apt.
If you decide to use apt anyway, note that for compatibility reasons, you’ll only be able to use the default Python versions that are available in Ubuntu (e.g. for Trusty, this means 2.7.6 and 3.4.3).
To access the packages inside the virtualenv, you will need to specify that it should be created with the
To do this, include the following in your
language: python python: - "2.7" - "3.4" virtualenv: system_site_packages: true
PyPy Support #
Travis CI supports PyPy and PyPy3.
To test your project against PyPy, add “pypy3.5” to the list of Pythons
language: python python: - "2.7" - "3.5" - "3.6" # PyPy versions - "pypy3.5" # command to install dependencies install: - pip install -r requirements.txt - pip install . # command to run tests script: pytest
Nightly build support #
Travis CI supports a special version name
nightly, which points to
a recent development version of CPython build.
Development releases support #
From Python 3.5 and later, Python In Development versions are available.
You can specify these in your builds with
Recent Python branches require OpenSSL 1.0.2+. As this library is not available for Trusty,
nightlydo not work (or use outdated archive).
Default Build Script #
Python projects need to provide the
script key in their
specify what command to run tests with.
For example, if your project uses pytest:
# command to run tests script: pytest
if it uses
make test instead:
script: make test
If you do not provide a
script key in a Python project, Travis CI prints a
message (“Please override the script: key in your .travis.yml to run tests.”)
and fails the build.
Using Tox as the Build Script #
Due to the way Travis is designed, interaction with tox is not straightforward.
As described above, Travis already runs tests inside an isolated virtualenv whenever
language: python is specified, so please bear that in mind whenever creating more environments with tox. If you would prefer to run tox outside the Travis-created virtualenv, it might be a better idea to use
language: generic instead of
If you’re using tox to test your code against multiple versions of python, you have two options:
language: genericand manually install the python versions you’re interested in before running tox (without the manual installation, tox will only have access to the default Ubuntu python versions - 2.7.6 and 3.4.3 for Trusty)
language: pythonand a build matrix that uses a different version of python for each branch (you can specify the python version by using the
pythonkey). This will ensure the versions you’re interested in are installed and parallelizes your workload.
A good example of a
travis.yml that runs tox using a Travis build matrix is twisted/klein.
Running Python tests on multiple Operating Systems #
Sometimes it is necessary to ensure that software works the same across multiple Operating Systems. This following
.travis.yml file will execute parallel test runs on Linux, macOS, and Windows.
language: python # this works for Linux but is an error on macOS or Windows matrix: include: - name: "Python 3.7.1 on Xenial Linux" python: 3.7 # this works for Linux but is ignored on macOS or Windows dist: xenial # required for Python >= 3.7 - name: "Python 3.7.2 on macOS" os: osx osx_image: xcode10.2 # Python 3.7.2 running on macOS 10.14.3 language: shell # 'language: python' is an error on Travis CI macOS - name: "Python 3.7.3 on Windows" os: windows # Windows 10.0.17134 N/A Build 17134 language: shell # 'language: python' is an error on Travis CI Windows before_install: choco install python env: PATH=/c/Python37:/c/Python37/Scripts:$PATH install: pip3 install --upgrade pip # all three OSes agree about 'pip3' # 'python' points to Python 2.7 on macOS but points to Python 3.7 on Linux and Windows # 'python3' is a 'command not found' error on Windows but 'py' works on Windows only script: python3 my_app.py || python my_app.py
Dependency Management #
By default Travis CI uses
pip to manage Python dependencies. If you have a
requirements.txt file, Travis CI runs
pip install -r requirements.txt
install phase of the build.
You can manually override this default
install phase, for example:
install: pip install --user -r requirements.txt
Please note that the
--user option is mandatory if you are not using
language: python, since no virtualenv will be created in that case.
Custom Dependency Management #
To override the default
pip dependency management, alter the
step as described in general build
Testing Against Multiple Versions of Dependencies (e.g. Django or Flask) #
If you need to test against multiple versions of, say, Django, you can instruct Travis CI to do multiple runs with different sets or values of environment variables.
Use env key in your .travis.yml file, for example:
env: - DJANGO_VERSION=1.10.8 - DJANGO_VERSION=1.11.5
and then use ENV variable values in your dependencies installation scripts, test cases or test script parameter values. Here we use ENV variable value to instruct pip to install an exact version:
install: - pip install -q Django==$DJANGO_VERSION - python setup.py -q install
The same technique is often used to test projects against multiple databases and so on.