Top Related Projects
Simple Python version management
A conda-forge distribution.
A system-level, binary package and environment manager running on all major operating systems and platforms.
Python extension for Visual Studio Code
Python packaging and dependency management made easy
Quick Overview
actions/setup-python is a GitHub Action that sets up a Python environment for use in GitHub Actions workflows. It allows users to easily specify and install Python versions, manage dependencies, and configure Python-related settings for their CI/CD pipelines.
Pros
- Supports multiple Python versions, including specific patch versions
- Automatically adds the installed Python to the PATH
- Caches pip dependencies for faster workflow execution
- Works across different operating systems (Windows, macOS, Linux)
Cons
- Limited to GitHub Actions ecosystem
- May require additional configuration for complex Python environments
- Does not support legacy Python versions (e.g., Python 2.x)
- Can increase workflow execution time when installing new Python versions
Getting Started
To use actions/setup-python in your GitHub Actions workflow, add the following step to your workflow file:
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.10'
- run: python my_script.py
This example sets up Python 3.10 and runs a Python script. You can customize the Python version and add additional steps as needed:
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.9'
architecture: 'x64'
cache: 'pip'
- run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
- run: python run_tests.py
This example sets up Python 3.9 for x64 architecture, enables pip caching, installs dependencies from a requirements file, and runs tests.
For more advanced usage, you can specify multiple Python versions:
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ['3.7', '3.8', '3.9', '3.10']
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- run: python my_script.py
This example runs the workflow with multiple Python versions in parallel.
Competitor Comparisons
Simple Python version management
Pros of pyenv
- Supports local development environments, not limited to CI/CD workflows
- Allows managing multiple Python versions on a single machine
- Provides a more comprehensive set of Python versions and implementations
Cons of pyenv
- Requires manual installation and setup on the local machine
- More complex to use, with a steeper learning curve
- May require additional configuration for integration with CI/CD pipelines
Code Comparison
setup-python:
- uses: actions/setup-python@v2
with:
python-version: '3.9'
pyenv:
pyenv install 3.9.0
pyenv global 3.9.0
setup-python is designed specifically for GitHub Actions, making it easier to integrate into CI/CD workflows. It's more straightforward to use but limited to the GitHub Actions environment. pyenv offers greater flexibility and control over Python versions across different environments but requires more setup and management. The choice between the two depends on the specific needs of the project and development workflow.
A conda-forge distribution.
Pros of miniforge
- Provides a full Conda environment, including package management
- Supports a wider range of Python versions and architectures
- Offers better compatibility with scientific and data science libraries
Cons of miniforge
- Larger download size and longer setup time
- More complex configuration for simple Python projects
- May introduce unnecessary dependencies for basic Python scripts
Code comparison
setup-python:
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- run: pip install numpy pandas
miniforge:
- uses: conda-forge/miniforge-ci-action@v1
with:
python-version: '3.9'
- run: |
conda install numpy pandas
conda activate base
The setup-python action is simpler and faster for basic Python projects, while miniforge provides a more comprehensive environment for complex scientific computing tasks. setup-python is ideal for lightweight CI/CD pipelines, whereas miniforge excels in scenarios requiring specific Conda packages or cross-platform compatibility. Choose based on your project's requirements and complexity.
A system-level, binary package and environment manager running on all major operating systems and platforms.
Pros of conda
- Supports multiple programming languages and package management
- Allows creation of isolated environments with specific dependencies
- Provides better control over package versions and conflicts
Cons of conda
- Larger installation size and slower initial setup
- Steeper learning curve for beginners
- May have compatibility issues with some packages
Code comparison
setup-python:
- uses: actions/setup-python@v3
with:
python-version: '3.x'
- run: pip install -r requirements.txt
conda:
- uses: conda-incubator/setup-miniconda@v2
with:
activate-environment: myenv
environment-file: environment.yml
- run: conda activate myenv
setup-python is simpler and more straightforward for basic Python setups, while conda offers more flexibility and control over the environment. setup-python is ideal for projects that only require Python, whereas conda is better suited for complex scientific computing environments or projects involving multiple languages.
Python extension for Visual Studio Code
Pros of vscode-python
- Provides a comprehensive Python development environment within VS Code
- Offers features like IntelliSense, debugging, and linting for Python
- Integrates with Jupyter Notebooks and interactive Python environments
Cons of vscode-python
- Larger and more complex, requiring more resources to run
- Primarily focused on VS Code integration, limiting its use in other contexts
- May have a steeper learning curve for users unfamiliar with VS Code
Code Comparison
setup-python:
- uses: actions/setup-python@v4
with:
python-version: '3.10'
vscode-python:
{
"python.pythonPath": "/path/to/python",
"python.linting.enabled": true,
"python.formatting.provider": "black"
}
The setup-python action is used in GitHub Actions workflows to set up a Python environment, while vscode-python configurations are typically found in VS Code settings files to customize the Python development experience within the editor.
setup-python is more focused on CI/CD pipelines and automation, while vscode-python enhances the development experience in VS Code. The choice between them depends on the specific use case: GitHub Actions workflows or local development in VS Code.
Python packaging and dependency management made easy
Pros of Poetry
- Comprehensive dependency management and packaging tool
- Virtual environment creation and management built-in
- Lockfile for reproducible builds across different environments
Cons of Poetry
- Steeper learning curve for beginners
- May require additional configuration in CI/CD pipelines
- Not as widely adopted as pip and requirements.txt
Code Comparison
setup-python:
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- run: pip install -r requirements.txt
Poetry:
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- uses: snok/install-poetry@v1
- run: poetry install
Summary
setup-python is a GitHub Action for setting up Python environments, while Poetry is a comprehensive Python packaging and dependency management tool. setup-python is simpler to use and widely adopted, making it ideal for straightforward projects. Poetry offers more advanced features like virtual environment management and lockfiles, but may require additional setup in CI/CD pipelines. The choice between the two depends on project complexity and team preferences.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
setup-python
This action provides the following functionality for GitHub Actions users:
- Installing a version of Python or PyPy and (by default) adding it to the PATH
- Optionally caching dependencies for pip, pipenv and poetry
- Registering problem matchers for error output
Breaking changes in V6
- Upgraded action from node20 to node24
Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release. See Release Notes
For more details, see the full release notes on the releases page
Basic usage
See action.yml
Python
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: '3.13'
- run: python my_script.py
PyPy
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: 'pypy3.10'
- run: python my_script.py
GraalPy
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: 'graalpy-24.0'
- run: python my_script.py
Free threaded Python
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: '3.13t'
- run: python my_script.py
The python-version input is optional. If not supplied, the action will try to resolve the version from the default .python-version file. If the .python-version file doesn't exist Python or PyPy version from the PATH will be used. The default version of Python or PyPy in PATH varies between runners and can be changed unexpectedly so we recommend always setting Python version explicitly using the python-version or python-version-file inputs.
The action will first check the local tool cache for a semver match. If unable to find a specific version in the tool cache, the action will attempt to download a version of Python from GitHub Releases and for PyPy from the official PyPy's dist.
For information regarding locally cached versions of Python or PyPy on GitHub hosted runners, check out GitHub Actions Runner Images.
Supported version syntax
The python-version input supports the Semantic Versioning Specification and some special version notations (e.g. semver ranges, x.y-dev syntax, etc.), for detailed examples please refer to the section: Using python-version input of the Advanced usage guide.
Supported architectures
Using the architecture input, it is possible to specify the required Python or PyPy interpreter architecture: x86, x64, or arm64. If the input is not specified, the architecture defaults to the host OS architecture.
Caching packages dependencies
The action has built-in functionality for caching and restoring dependencies. It uses toolkit/cache under the hood for caching dependencies but requires less configuration settings. Supported package managers are pip, pipenv and poetry. The cache input is optional, and caching is turned off by default.
The action defaults to searching for a dependency file (requirements.txt or pyproject.toml for pip, Pipfile.lock for pipenv or poetry.lock for poetry) in the repository, and uses its hash as a part of the cache key. Input cache-dependency-path is used for cases when multiple dependency files are used, they are located in different subdirectories or different files for the hash that want to be used.
- For
pip, the action will cache the global cache directory - For
pipenv, the action will cache virtualenv directory - For
poetry, the action will cache virtualenv directories -- one for each poetry project found
Caching pip dependencies:
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: '3.13'
cache: 'pip' # caching pip dependencies
- run: pip install -r requirements.txt
Note: Restored cache will not be used if the requirements.txt file is not updated for a long time and a newer version of the dependency is available which can lead to an increase in total build time.
The requirements file format allows for specifying dependency versions using logical operators (for example chardet>=3.0.4) or specifying dependencies without any versions. In this case the pip install -r requirements.txt command will always try to install the latest available package version. To be sure that the cache will be used, please stick to a specific dependency version and update it manually if necessary.
The
setup-pythonaction does not handle authentication for pip when installing packages from private repositories. For help, refer pipâs VCS support documentation or visit the pip repository.
See examples of using cache and cache-dependency-path for pipenv and poetry in the section: Caching packages of the Advanced usage guide.
Advanced usage
- Using the python-version input
- Using the python-version-file input
- Check latest version
- Caching packages
- Outputs and environment variables
- Available versions of Python, PyPy and GraalPy
- Hosted tool cache
- Using
setup-pythonwith a self-hosted runner - Using
setup-pythonon GHES - Allow pre-releases
- Using the pip-version input
- Using the pip-install input
Recommended permissions
When using the setup-python action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:
permissions:
contents: read # access to check out code and install dependencies
License
The scripts and documentation in this project are released under the MIT License.
Contributions
Contributions are welcome! See our Contributor's Guide.
Top Related Projects
Simple Python version management
A conda-forge distribution.
A system-level, binary package and environment manager running on all major operating systems and platforms.
Python extension for Visual Studio Code
Python packaging and dependency management made easy
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot