> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/python

Common CircleCI tasks for the Python programming language.
Supports Linux x86_64, MacOS, and Arm64 V8.


## Commands

### dist

Build a distribution package

| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | . | Path to the directory containing your python project. Not needed if 'setup.py' lives in root project dir. |
| `build-tool` | enum | wheel | Choose the build command to run. Options include PEP427 wheel (default) and PEP517 build. |
| `no-isolation` | boolean | false | Do not isolate the build in a virtual environment. Exclusive to build-tool option "build" only. |
| `out-dir` | string | ./dist | Path where to write the output files. |
| `sdist-separate` | boolean | false | Opt out of default behavior and build sdist independently from wheel. Exclusive to build-tool option "build" only. |
| `skip-dependency-check` | boolean | false | Do not check that build dependencies are installed. Exclusive to build-tool option "build" only. |
| `wheel-separate` | boolean | false | Build a wheel directly from the source. Default behavior builds an sdist, then builds a wheel from that sdist. Exclusive to build-tool option "build" only. |

### install-packages

Setup a python environment and install the packages for your project either globally with pip or in a virtualenv with poetry or pipenv. With pip as pkg-manager, the command will assume `-r requirements.txt`. With poetry as pkg-manager, the command will assume `--no-ansi`. For pipenv, no args are provided. Expect the default caching locations for packages and virtualenvs on a debian system with pyenv.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | . | Path to the directory containing your python project. Not needed if dependency file lives in the root. |
| `args` | string |  | Arguments to pass to install command for pipenv and poetry. For pip, arguments are after the command, `pip install -r requirements.txt <args>`.
For poetry, args are after `--no-ansi` as output option.
 |
| `cache-folder-prefix` | string | /tmp/cache | A directory where you would like to save the cache files. Defaults to empty, saving the cache to project folder.
If you don't want the cache in your project directory, specify the absolute path of an existing directory here.
 |
| `cache-key-override` | string |  | Override the built-in cache key. If set, this value will be used as the cache key for restore_cache/save_cache steps.
You can use CircleCI template functions, e.g.:
  cache-key-override: "pip-{{ checksum 'dev-requirements.txt' }}-{{ checksum 'requirements.txt' }}"
If not set, the default cache key logic will be used.
 |
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason. |
| `include-branch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `include-python-in-cache-key` | boolean | true | If true, this cache bucket will checksum the pyenv python version with the cache-key.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. Passed to install command. |
| `path-args` | string | . | If using `pip-dist` these are the arguments after the command `pip install -e` that is by default set to `.`.  Use of this parameter allows
for multiple paths to be specified.  This is important when extra paths are required to install extra packages referenced via `extras_requires`.
 |
| `pip-dependency-file` | string | requirements.txt | Name of the requirements file that needs to be installed with pip. Prepended with `app-dir`. If using pipenv or poetry, this is ignored.
If using `pip-dist`, use this to use the cache checksum against the `setup.py` or `pyproject.toml` if desired.
If `pip-dependency-file` is set to an empty string, no dependency file is used in the `pip install` command.
 |
| `pkg-manager` | enum | auto | Which package management tool to use, pipenv, pip or poetry with dependency file. Use `pip-dist` to install with project setup.py or PEP621 (pyproject.toml). |
| `pre-install-steps` | steps |  | Steps needed between restoring the cache and the install step.
 |
| `pypi-cache` | boolean | true | Keep all versions of pypi and site-package caches for faster rebuilding overall. |
| `venv-cache` | boolean | true | Use the lockfile to cache the virtualenv. Not used with pip as pkg-manager. |
| `venv-path` | string |  | Override venv path. As json array - ex '[ "path", "path2" ]' |

## Jobs

### test

Simple drop-in job to setup a python project, run tests and store the test results if possible.
If test-tool is pytest, the job assumes the project defines pytest in the dependency file.
Otherwise, use the built in unittest module as the test-tool.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | ~/project | Path to the directory containing your python project. Not needed if dependency file lives in the root. |
| `args` | string |  | Arguments to pass to install command for pipenv, poetry or uv. Override '-r requirements.txt' for pip. |
| `cache-folder-prefix` | string | /tmp/cache | A directory where you would like to save the cache files. Defaults to empty, saving the cache to project folder.
If you don't want the cache in your project directory, specify the absolute path of an existing directory here.
 |
| `cache-version` | string | v1 | Change the default cache version if you need to clear the cache for any reason. |
| `ensure-test-tool` | boolean | true | If true, a step will be ran to ensure the configured test tool is installed.
 |
| `executor` | executor | default | The name of executor to use.
 |
| `fail-if-missing-tool` | boolean | false | If true, this job will fail if the test tool was not found. If false, it will automatically install to recover.
 |
| `include-branch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `include-python-in-cache-key` | boolean | true | If true, this cache bucket will checksum the pyenv python version with the cache-key
 |
| `module-src-dir` | string | src | Path relative to app-dir which contains module source. |
| `pip-dependency-file` | string | requirements.txt | Name of the requirements file that needs to be installed with pip. Prepended with `app-dir`. If using pipenv, poetry or uv, this is ignored. |
| `pkg-manager` | enum | auto | Select the package manager to use. Default is pip |
| `pre-install-steps` | steps |  | Steps needed between restoring the cache and the install step.
 |
| `pypi-cache` | boolean | true | Keep all versions of pypi and site-package caches for faster rebuilding overall. |
| `setup` | steps |  | Provide any optional steps you would like to run prior to install the python project. |
| `setup-file-path` | string |  | Path to the setup.py file. |
| `test-tool` | enum | pytest | The tool to run the tests with. |
| `test-tool-args` | string |  | Arguments to pass to test tool, i.e. discovery settings for unittest - 'discover -s tests_dir'. |
| `venv-cache` | boolean | true | Use the lockfile to cache the virtualenv. Not used with pip as pkg-manager. |

## Executors

### default

The official CircleCI CIMG Python Docker image.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | 3.14 | The `cimg/python` Docker image version tag. |

## Examples

### using-test-job

An example of running a pipenv based project with pytest. And then using twine to publish to pypi.
The project using these args would have pytest as a dev dependency in its Pipfile.
The CircleCI project settings would have the environment variables for twine auth.


```yaml
version: '2.1'
orbs:
  python: circleci/python@4.0.0
jobs:
  publish:
    executor:
      name: python/default
      tag: '3.14'
    steps:
      - checkout
      - python/dist
      - run: pip install twine && twine upload dist/*
workflows:
  main:
    jobs:
      - python/test:
          args: '--dev'
          pkg-manager: pipenv
          test-tool: pytest
      - publish
```

### work-with-pip

An example of working with the Pip and caching requirements.txt on CircleCI to speed up builds.


```yaml
version: '2.1'
orbs:
  python: circleci/python@4.0.0
jobs:
  build:
    executor:
      name: python/default
      tag: '3.14'
    steps:
      - checkout
      - python/install-packages:
          pkg-manager: pip
      - python/install-packages:
          cache-key-override: >-
            pip-{{ checksum 'dev-requirements.txt' }}-{{ checksum
            'requirements.txt' }}
          pkg-manager: pip
      - python/install-packages:
          pip-dependency-file: dev-requirements.txt
          pkg-manager: pip
      - python/install-packages:
          args: pytest
          pkg-manager: pip
          pypi-cache: false
      - run:
          command: |
            pytest --version
          name: Test
workflows:
  main:
    jobs:
      - build
```

### work-with-pipenv

An example of working with the Pipenv cache on CircleCI to speed up builds.


```yaml
version: '2.1'
orbs:
  python: circleci/python@4.0.0
jobs:
  build:
    executor:
      name: python/default
      tag: '3.14'
    steps:
      - checkout
      - python/install-packages:
          args: pytest
          pkg-manager: pipenv
      - run:
          command: |
            pipenv run pytest --version
          name: Test it
workflows:
  main:
    jobs:
      - build
```

### work-with-poetry

An example of working with the Poetry cache on CircleCI to speed up builds.


```yaml
version: '2.1'
orbs:
  python: circleci/python@4.0.0
jobs:
  build:
    executor:
      name: python/default
      tag: '3.14'
    steps:
      - checkout
      - python/install-packages:
          pkg-manager: poetry
      - run:
          command: |
            poetry run pytest --version
          name: Test it
workflows:
  main:
    jobs:
      - build
```

### work-with-uv

An example of working with the uv cache on CircleCI to speed up builds.


```yaml
version: '2.1'
orbs:
  python: circleci/python@4.0.0
jobs:
  build:
    executor:
      name: python/default
      tag: '3.14'
    steps:
      - checkout
      - python/install-packages:
          pkg-manager: uv
      - run:
          command: |
            uv run pytest --version
          name: Test it
workflows:
  main:
    jobs:
      - build
```