Configure a Python application on CircleCI
On This Page
Setup your Python App
Learn to build, test, and deploy your Python app.
15 min task
This is a quickstart guide for integrating a Python project with CircleCI. This guide is designed to help you create a basic CircleCI configuration file to build, test and deploy your Python project. After completing this quickstart you can edit and optimize the config to fit the requirements of your project.
- A CircleCI account
- A Python project located in a supported VCS
If you do not have a Python project, but would like to follow this guide, you can use our sample project which is hosted on GitHub and is building on CircleCI. Consider forking the repository and rewriting the configuration file as you follow this guide.
Every CircleCI project requires a configuration file called
.circleci/config.yml. Follow the steps below to create a working
1. Specify a version
Every CircleCI config.yml starts with the version key. This key is used to issue warnings about breaking changes.
2.1 is the latest CircleCI version, and it ensures you have access to all our latest features and improvements.
2. Use the Python orb
The Python orb contains a set of prepackaged CircleCI configurations you can use to do common CircleCI tasks for the Python programming language. It supports Linux x86_64, macOS x86_64, and Arm64. Learn more about orbs.
To add the orb to your config, insert:
orbs: python: firstname.lastname@example.org
Note: When using an orb, it is a good idea to check the Orb Registry to ensure you are using the most recent version, or the version that fits best with your specific project.
3. Create jobs
Jobs are the building blocks of your config. Jobs are collections of steps, which run commands/scripts as required. All of the steps in the job are executed in a single unit, either within a fresh container or virtual machine. Learn more about jobs on the Jobs and Steps page.
A common ask from developers who are getting started with CircleCI is to perform three basic tasks:
deploy. This section guides you through each of the config changes needed. Because we are using the official Python orb, we can use commands that are built into the orb to keep our config simple and succinct:
a. Build and test the app
For this step, we are using the
python/install-packages command that comes from the Python orb. This command automatically sets up a python environment and installs the packages for your project either globally with
pip or in a
jobs: build_and_test: # this can be any name you choose executor: python/default # use the default executor defined within the orb steps: - checkout # checkout source code - python/install-packages: pkg-manager: pip - run: name: Run tests command: python -m pytest - persist_to_workspace: root: ~/project paths: - .
b. Deploy the app
In this quickstart guide, we will deploy to Heroku. We can do this using the official Heroku orb by adding a new line into our orb section. The Heroku orb contains a set of prepackaged CircleCI configurations you can use to deploy applications to Heroku. Learn more about the Heroku orb.
orbs: python: email@example.com heroku: firstname.lastname@example.org
We then need to add a job to our list to take care of the deploy step:
jobs: # ...previous job(s)... deploy: # this can be any name you choose executor: heroku/default # use the default executor defined within the orb steps: - attach_workspace: at: ~/project - heroku/deploy-via-git: force: true # force push when pushing to the heroku remote, see: https://devcenter.heroku.com/articles/git
4. Create a workflow
A workflow is a set of rules for defining a collection of jobs and their run order. Workflows support complex job orchestration using a set of configuration keys to help you resolve failures sooner. Inside the workflow, you define the jobs you want to run. CircleCI will run this workflow on every commit. Learn more about workflow configuration.
workflows: build_test_deploy: # this can be any name you choose
5. Add jobs to the workflow
Now that we have our workflow,
build_test_deploy, we can use it to orchestrate the running of our
deploy jobs. Refer to the Using Workflows to Orchestrate Jobs page for more details about orchestrating jobs with concurrent, sequential, and manual approval workflows.
workflows: build_test_deploy: jobs: - build_and_test - deploy: requires: - build_and_test # only deploy if the build_and_test job has completed filters: branches: only: main # only deploy when on main
You just set up a Python app to build on CircleCI. Check out your project’s pipeline page to see how this looks when building on CircleCI.
Full configuration file
version: 2.1 orbs: python: email@example.com heroku: firstname.lastname@example.org jobs: build_and_test: # this can be any name you choose executor: python/default steps: - checkout - python/install-packages: pkg-manager: pip - run: name: Run tests command: python -m pytest - persist_to_workspace: root: ~/project paths: - . deploy: # this can be any name you choose executor: python/default steps: - attach_workspace: at: ~/project - heroku/deploy-via-git: force: true # force push when pushing to the heroku remote, see: https://devcenter.heroku.com/articles/git workflows: test_my_app: jobs: - build_and_test - deploy: requires: - build_and_test # only deploy if the build_and_test job has completed filters: branches: only: main # only deploy when on main
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.