{"id":33338700,"url":"https://github.com/step-security/install-poetry","last_synced_at":"2026-03-02T16:38:56.653Z","repository":{"id":325211551,"uuid":"1100281466","full_name":"step-security/install-poetry","owner":"step-security","description":"Github action for installing and configuring Poetry. Secure drop-in replacement for snok/install-poetry.","archived":false,"fork":false,"pushed_at":"2025-11-21T08:00:31.000Z","size":42,"stargazers_count":0,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-21T10:04:14.673Z","etag":null,"topics":["step-security-maintained-actions"],"latest_commit_sha":null,"homepage":"https://docs.stepsecurity.io/actions/stepsecurity-maintained-actions","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/step-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T04:35:58.000Z","updated_at":"2025-11-21T06:20:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/step-security/install-poetry","commit_stats":null,"previous_names":["step-security/install-poetry"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/step-security/install-poetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/step-security%2Finstall-poetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/step-security%2Finstall-poetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/step-security%2Finstall-poetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/step-security%2Finstall-poetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/step-security","download_url":"https://codeload.github.com/step-security/install-poetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/step-security%2Finstall-poetry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30009969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T15:15:59.058Z","status":"ssl_error","status_checked_at":"2026-03-02T15:15:58.758Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["step-security-maintained-actions"],"created_at":"2025-11-21T10:00:21.552Z","updated_at":"2026-03-02T16:38:56.648Z","avatar_url":"https://github.com/step-security.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Install Poetry Action\n\nA Github action for installing and configuring [Poetry](https://python-poetry.org/).\n\nThe action installs Poetry, adds executables to the runner system path, and sets relevant Poetry config settings.\n\n## Usage\n\nIf all you need is default Poetry, simply add this to your workflow:\n\n```yaml\n- name: Install Poetry\n  uses: step-security/install-poetry@v1\n```\n\nIf you want to set Poetry config settings, or install a specific version, you can specify inputs:\n\n```yaml\n- name: Install and configure Poetry\n  uses: step-security/install-poetry@v1\n  with:\n    version: 2.1.3\n    virtualenvs-create: true\n    virtualenvs-in-project: false\n    virtualenvs-path: ~/my-custom-path\n    installer-parallel: true\n```\n\nIf you need to pass extra arguments to the installer script, you can specify these with `installation-arguments`.\n\nThe action is fully tested for macOS and Ubuntu runners, on Poetry versions \u003e= 1.1. If you're using this with Windows, see the [Running on Windows](#running-on-windows) section.\n\n## Defaults\n\nThe current default settings are:\n\n```yaml\nversion: latest\nvirtualenvs-create: true\nvirtualenvs-in-project: false\nvirtualenvs-path: {cache-dir}/virtualenvs\ninstaller-parallel: true\n```\n\nYou can specify installation arguments directly to the poetry installer using the installation-arguments in the following\nway:\n\n```yaml\n- name: Install and configure Poetry\n  uses: step-security/install-poetry@v1\n  with:\n    installation-arguments: --git https://github.com/python-poetry/poetry.git@69bd6820e320f84900103fdf867e24b355d6aa5d\n```\n\nIf you want to make further config changes - e.g., to change one of the `experimental` Poetry config settings, or just\nto make changes to the Poetry config *after* invoking the action - you can do so in a subsequent step, like this:\n\n```yaml\n- uses: step-security/install-poetry@v1\n- run: poetry config experimental.new-installer false\n```\n\n## Workflow examples and tips\n\nThis section contains a collection of workflow examples to try and help\n\n- Give you a starting point for setting up your own workflows\n- Demonstrate how to implement caching for performance improvements\n- Clarify the implications of different settings\n\nSome examples are a bit long, so here are some links\n\n- [Install Poetry Action](#install-poetry-action)\n  - [Usage](#usage)\n  - [Defaults](#defaults)\n  - [Workflow examples and tips](#workflow-examples-and-tips)\n      - [Testing](#testing)\n      - [Testing using a matrix](#testing-using-a-matrix)\n      - [Codecov upload](#codecov-upload)\n      - [Running on Windows](#running-on-windows)\n        - [Caching on Windows runners](#caching-on-windows-runners)\n      - [Virtualenv variations](#virtualenv-variations)\n      - [Caching the Poetry installation](#caching-the-poetry-installation)\n      - [Installing Poetry Plugins](#installing-poetry-plugins)\n  - [License](#license)\n\n#### Testing\n\nA basic example workflow for running your test-suite can be structured like this.\n\n```yaml\nname: test\n\non: pull_request\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      #----------------------------------------------\n      #       check-out repo and set-up python\n      #----------------------------------------------\n      - name: Check out repository\n        uses: actions/checkout@v5\n      - name: Set up python\n        id: setup-python\n        uses: actions/setup-python@v6\n        with:\n          python-version: '3.13'\n      #----------------------------------------------\n      #  -----  install \u0026 configure poetry  -----\n      #----------------------------------------------\n      - name: Install Poetry\n        uses: step-security/install-poetry@v1\n        with:\n          virtualenvs-create: true\n          virtualenvs-in-project: true\n          virtualenvs-path: .venv\n          installer-parallel: true\n\n      #----------------------------------------------\n      #       load cached venv if cache exists\n      #----------------------------------------------\n      - name: Load cached venv\n        id: cached-poetry-dependencies\n        uses: actions/cache@v4\n        with:\n          path: .venv\n          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}\n      #----------------------------------------------\n      # install dependencies if cache does not exist\n      #----------------------------------------------\n      - name: Install dependencies\n        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'\n        run: poetry install --no-interaction --no-root\n      #----------------------------------------------\n      # install your root project, if required\n      #----------------------------------------------\n      - name: Install project\n        run: poetry install --no-interaction\n      #----------------------------------------------\n      #              run test suite\n      #----------------------------------------------\n      - name: Run tests\n        run: |\n          source .venv/bin/activate\n          pytest tests/\n          coverage report\n```\n\n#### Testing using a matrix\n\nA more extensive example for running your test-suite on combinations of multiple operating systems, python versions, or\npackage-versions, can be structured like this.\n\n*The linting job has nothing to do with the matrix, and is only included for inspiration.*\n\n```yaml\nname: test\n\non: pull_request\n\njobs:\n  linting:\n    runs-on: ubuntu-latest\n    steps:\n      #----------------------------------------------\n      #       check-out repo and set-up python\n      #----------------------------------------------\n      - uses: actions/checkout@v5\n      - uses: actions/setup-python@v6\n      #----------------------------------------------\n      #        load pip cache if cache exists\n      #----------------------------------------------\n      - uses: actions/cache@v4\n        with:\n          path: ~/.cache/pip\n          key: ${{ runner.os }}-pip\n          restore-keys: ${{ runner.os }}-pip\n      #----------------------------------------------\n      #          install and run linters\n      #----------------------------------------------\n      - run: python -m pip install black flake8 isort\n      - run: |\n          flake8 .\n          black . --check\n          isort .\n  test:\n    needs: linting\n    strategy:\n      fail-fast: true\n      matrix:\n        os: [ \"ubuntu-latest\", \"macos-latest\" ]\n        python-version: [ \"3.8\", \"3.9\", \"3.10\", \"3.11\", \"3.13\" ]\n        django-version: [ \"4\", \"5\" ]\n    runs-on: ${{ matrix.os }}\n    steps:\n      #----------------------------------------------\n      #       check-out repo and set-up python\n      #----------------------------------------------\n      - name: Check out repository\n        uses: actions/checkout@v5\n      - name: Set up python ${{ matrix.python-version }}\n        id: setup-python\n        uses: actions/setup-python@v6\n        with:\n          python-version: ${{ matrix.python-version }}\n      #----------------------------------------------\n      #  -----  install \u0026 configure poetry  -----\n      #----------------------------------------------\n      - name: Install Poetry\n        uses: step-security/install-poetry@v1\n        with:\n          virtualenvs-create: true\n          virtualenvs-in-project: true\n      #----------------------------------------------\n      #       load cached venv if cache exists\n      #----------------------------------------------\n      - name: Load cached venv\n        id: cached-poetry-dependencies\n        uses: actions/cache@v4\n        with:\n          path: .venv\n          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}\n      #----------------------------------------------\n      # install dependencies if cache does not exist\n      #----------------------------------------------\n      - name: Install dependencies\n        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'\n        run: poetry install --no-interaction --no-root\n      #----------------------------------------------\n      # install your root project, if required\n      #----------------------------------------------\n      - name: Install library\n        run: poetry install --no-interaction\n      #----------------------------------------------\n      #    add matrix specifics and run test suite\n      #----------------------------------------------\n      - name: Install django ${{ matrix.django-version }}\n        run: |\n          source .venv/bin/activate\n          pip install \"Django==${{ matrix.django-version }}\"\n      - name: Run tests\n        run: |\n          source .venv/bin/activate\n          pytest tests/\n          coverage report\n```\n\n#### Codecov upload\n\nThis section contains a simple codecov upload. See the\n[codecov action](https://github.com/codecov/codecov-action) for more information.\n\n```yaml\nname: coverage\n\non:\n  push:\n    branches:\n      - master\n\njobs:\n  codecov:\n    runs-on: ubuntu-latest\n    steps:\n      #----------------------------------------------\n      #       check-out repo and set-up python\n      #----------------------------------------------\n      - uses: actions/checkout@v5\n      - uses: actions/setup-python@v6\n        id: setup-python\n        with:\n          python-version: '3.13'\n      #----------------------------------------------\n      #  -----  install \u0026 configure poetry  -----\n      #----------------------------------------------\n      - name: Install Poetry\n        uses: step-security/install-poetry@v1\n        with:\n          virtualenvs-create: true\n          virtualenvs-in-project: true\n      #----------------------------------------------\n      #       load cached venv if cache exists\n      #----------------------------------------------\n      - name: Load cached venv\n        id: cached-poetry-dependencies\n        uses: actions/cache@v4\n        with:\n          path: .venv\n          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}\n      #----------------------------------------------\n      # install dependencies if cache does not exist\n      #----------------------------------------------\n      - name: Install dependencies\n        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'\n        run: poetry install --no-interaction --no-root\n      #----------------------------------------------\n      # install your root project, if required\n      #----------------------------------------------\n      - name: Install library\n        run: poetry install --no-interaction\n      #----------------------------------------------\n      #    run test suite and output coverage file\n      #----------------------------------------------\n      - name: Test with pytest\n        run: poetry run pytest --cov=\u003cproject-dir\u003e --cov-report=xml\n      #----------------------------------------------\n      #             upload coverage stats\n      # (requires CODECOV_TOKEN in repository secrets)\n      #----------------------------------------------\n      - name: Upload coverage\n        uses: codecov/codecov-action@v3\n        with:\n          token: ${{ secrets.CODECOV_TOKEN }}  # Only required for private repositories\n          file: ./coverage.xml\n          fail_ci_if_error: true\n```\n\n#### Running on Windows\n\nRunning this action on Windows is supported, but two things are important to note:\n\n1. You need to set the job-level default shell to `bash`\n\n    ```yaml\n    defaults:\n      run:\n        shell: bash\n    ```\n2. If you are running an OS matrix, and want to activate your venv `in-project`\n   you have to deal with different folder structures on different operating systems. To make this work, you *can* do\n   this\n\n   ```yaml\n   - run: |\n       source .venv/scripts/activate\n       pytest --version\n     if: runner.os == 'Windows'\n   - run: |\n       source .venv/bin/activate\n       pytest --version\n     if: runner.os != 'Windows'\n   ```\n\n   but we think this is an annoying way to have to structure our workflows, so we set a custom environment\n   variable, `$VENV` which will point to the OS-specific venv activation script, whether you're running UNIX or Windows.\n   This means you can do this instead\n\n   ```yaml\n   - run: |\n       source $VENV\n       pytest --version\n   ```\n\nFor context, a full os-matrix using `windows-latest` could be set up like this:\n\n```yaml\nname: test\n\non: pull_request\n\njobs:\n  test-windows:\n    strategy:\n      matrix: [ \"ubuntu-latest\", \"macos-latest\", \"windows-latest\" ]\n    defaults:\n      run:\n        shell: bash\n    runs-on: ${{ matrix.os }}\n    steps:\n      - name: Check out repository\n        uses: actions/checkout@v5\n      - name: Set up python\n        id: setup-python\n        uses: actions/setup-python@v6\n        with:\n          python-version: '3.13'\n      - name: Install Poetry\n        uses: step-security/install-poetry@v1\n        with:\n          virtualenvs-create: true\n          virtualenvs-in-project: true\n      - name: Load cached venv\n        id: cached-pip-wheels\n        uses: actions/cache@v4\n        with:\n          path: ~/.cache\n          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}\n      - name: Install dependencies\n        run: poetry install --no-interaction --no-root\n      - name: Install library\n        run: poetry install --no-interaction\n      - run: |\n          source $VENV\n          pytest --version\n```\n\n##### Caching on Windows runners\n\nFor some reason, caching your `venv` does not seem to work as expected on Windows runners. The workflow stalls and runs for\nover 3 hours before it was manually cancelled.\n\nIf you do want to cache your dependencies on a Windows runner, you should look into caching your pip wheels instead of\nyour venv; this seems to work fine.\n\n#### Virtualenv variations\n\nAll of the examples we've added use these Poetry settings\n\n```yaml\n- name: Install Poetry\n  uses: step-security/install-poetry@v1\n  with:\n    virtualenvs-create: true\n    virtualenvs-in-project: true\n```\n\nWhile this should work for most, and we generally prefer creating our\n`virtualenvs` in-project to make the caching step as simple as possible, there are valid reasons for not wanting to\nconstruct a venv in your project directory.\n\nThere are two other relevant scenarios:\n\n1. Creating a venv, but not in the project dir\n\n   If you're using the default settings, the venv location changes from `.venv` to using `{cache-dir}/virtualenvs`. You\n   can also change the path to whatever you'd like. Generally though, this can make things a little tricky, because the\n   directory will be vary depending on the OS, making it harder to write OS-agnostic workflows.\n\n   A solution to this is to bypass this issue completely by taking advantage of Poetry's `poetry run` command.\n\n   Using the last two steps in the [Matrix testing](#mtesting) example as an example, this is how we have otherwise\n   documented installing a matrix-specific dependency and running the test suite:\n\n    ```yaml\n    - name: Install django ${{ matrix.django-version }}\n      run: |\n        source .venv/bin/activate\n        pip install \"Django==${{ matrix.django-version }}\"\n    - name: Run tests\n      run: |\n        source .venv/bin/activate\n        pytest tests/\n        coverage report\n    ```\n\n   With a remote venv you can do this instead:\n\n    ```yaml\n    - name: Install django ${{ matrix.django-version }}\n      run: poetry add \"Django==${{ matrix.django-version }}\"\n    - name: Run tests\n      run: |\n        poetry run pytest tests/\n        poetry run coverage report\n    ```\n\n   \u003e We have never needed to cache remote venvs in our workflows.\n   \u003e If you have, feel free to submit a PR explaining how it's done.\n\n2. Skipping venv creation\n\n   If you want to skip venv creation, all the original examples are made valid by simply removing the venv activation\n   line: `source .venv/bin/activate`.\n\n   To enable caching in this case, you will want to set up something resembling the linting job caching step in\n   the [Matrix testing](#mtesting); caching your pip wheels rather than your installed dependencies.\n\n   Since you're not caching your whole venv, you will need to re-install dependencies every time you run the job;\n   caching will, however, still save you the time it would take to download the wheels (and it will reduce the strain on\n   PyPi).\n\n#### Caching the Poetry installation\n\nIn addition to caching your python dependencies you might find it useful to cache the Poetry installation itself. This\nshould cut ~10 seconds of your total runtime and roughly 95% of this action's runtime.\n\n```yaml\nname: test\n\non: pull_request\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out repository\n        uses: actions/checkout@v5\n      - name: Set up python\n        uses: actions/setup-python@v6\n        with:\n          python-version: '3.13'\n      - name: Load cached Poetry installation\n        id: cached-poetry\n        uses: actions/cache@v4\n        with:\n          path: ~/.local  # the path depends on the OS\n          key: poetry-0  # increment to reset cache\n      - name: Install Poetry\n        if: steps.cached-poetry.outputs.cache-hit != 'true'\n        uses: step-security/install-poetry@v1\n```\n\nThe directory to cache will depend on the operating system of the runner.\n\nNote that when the cache is hit, and the Install Poetry step is skipped, configuration options are not re-applied. The cached Poetry installation will now run with default settings. To make things work the same, you may add a dedicated configuration step to re-apply your configurations. For example:\n\n```yaml\n- name: Configure poetry\n  if: steps.cached-poetry.outputs.cache-hit == 'true'\n  run: poetry config virtualenvs.in-project true\n```\n\nOr consider using a config.toml file to store you configuration options. See details in the [Poetry configuration docs](https://python-poetry.org/docs/configuration/).\n\n#### Installing Poetry Plugins\n\nWith Poetry 1.2 or later, you can use this action to install plugins:\n\n```yaml\n- uses: step-security/install-poetry@v1\n  with:\n    plugins: poetry-plugin-a\n```\n\nYou can use a whitespace delimited list:\n\n```yaml\n- uses: step-security/install-poetry@v1\n  with:\n    plugins: |\n      poetry-plugin-a\n      poetry-plugin-b\n```\n\n## License\n\ninstall-poetry is licensed under an MIT license. See the license file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstep-security%2Finstall-poetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstep-security%2Finstall-poetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstep-security%2Finstall-poetry/lists"}