# jf pip

Run pip install with Artifactory integration and optional build-info collection.

This topic covers the following tasks:

* [Configure pip for Artifactory (`jf pip-config`)](#configuration-jf-pip-config)
* [Run pip commands (`jf pip`)](#build-jf-pip)

## When to Use

Use `jf pip` if your Python project uses pip with `requirements.txt` for dependency management. For Pipenv-based projects (with `Pipfile`), use [`jf pipenv`](jf-pipenv.md). For Poetry-based projects (with `pyproject.toml`), use [`jf poetry`](jf-poetry.md).

## Prerequisites

* pip must be installed (Python 3.6+).
* Run `jf pip-config` in the project directory before the first install.
* Configure a server with `jf config add` or `jf c add`.
* Authentication to Artifactory is required.
* Using a Python [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) is recommended.

***

## Configuration: `jf pip-config`

Generate pip build configuration for dependency resolution and deployment. **Run this once per project before your first install.**

**To configure pip for Artifactory:**

### Synopsis

```
jf pip-config [options]
```

**Aliases:** `pipc`

### Configuration Options

| Flag                  | Default | Description                                                                          |
| --------------------- | ------- | ------------------------------------------------------------------------------------ |
| `--global`            | `false` | Set to true for global configuration (all projects). Specific projects can override. |
| `--repo-deploy`       | —       | Repository for artifacts deployment                                                  |
| `--repo-resolve`      | —       | Repository for dependencies resolution                                               |
| `--server-id-deploy`  | —       | Artifactory server ID for deployment. Configure with `jf config add`.                |
| `--server-id-resolve` | —       | Artifactory server ID for resolution. Configure with `jf config add`.                |

### Configuration Examples

#### View Help

```bash
jf pip-config --help
```

#### Non-Interactive Configuration with Flags

```bash
jf pip-config --server-id-resolve=<server-id> --repo-resolve=<repo-name> --server-id-deploy=<server-id> --repo-deploy=<repo-name>
```

Where:

* \<server-id>: The server ID configured using `jf config add`
* \<repo-name>: The name of the repository in Artifactory

For example:

```bash
jf pip-config --server-id-resolve=my-server --repo-resolve=pypi-virtual --server-id-deploy=my-server --repo-deploy=pypi-local
```

### Why Run Config First?

You must run `jf pip-config` **before** `jf pip install`. The config command creates `.jfrog/projects/pip.yaml` which directs pip to resolve from and deploy to Artifactory repositories. Without it, `jf pip` does not know where to fetch packages.

> **Shortcut**: In CI/CD, pass all flags non-interactively so the config step is fully automated and reproducible.

### Configuration Notes

* **Covers twine too**: This config also applies to `jf twine upload` for publishing Python packages.
* **Run once per project**: Re-run when changing repository assignments.
* **Resolution and deployment**: Use `--repo-resolve` for installing packages and `--repo-deploy` for publishing.

### Expected Output

```
$ jf pip-config --server-id-resolve=my-server --repo-resolve=pypi-virtual --server-id-deploy=my-server --repo-deploy=pypi-local
pip build configuration saved successfully.
```

### How to Verify

After running, confirm the configuration exists:

```bash
cat .jfrog/projects/pip.yaml
```

***

## Build: `jf pip`

Run pip install with Artifactory integration and optional build-info collection.

**To run pip with Artifactory integration:**

### Synopsis

```
jf pip <pip-arguments> [options]
```

**Aliases:** none

### Arguments

| Argument          | Required | Description                                                                  |
| ----------------- | -------- | ---------------------------------------------------------------------------- |
| `<pip-arguments>` | Yes      | Arguments and options for the pip command (for example, `install`, `freeze`) |

### Build Options

| Flag             | Default | Description                                                                        |
| ---------------- | ------- | ---------------------------------------------------------------------------------- |
| `--build-name`   | —       | Build name for build-info. Requires `--build-number`.                              |
| `--build-number` | —       | Build number for build-info. Requires `--build-name`.                              |
| `--module`       | —       | Optional module name for build-info. Requires `--build-name` and `--build-number`. |
| `--project`      | —       | JFrog Artifactory project key                                                      |

### Build Examples

#### View Help

```bash
jf pip --help
```

#### Install Dependencies with Build-Info

```bash
jf pip install -r requirements.txt --build-name=<build-name> --build-number=<build-number>
```

Where:

* `<build-name>` is a name for the build (e.g., `my-python-app`)
* `<build-number>` is a number or identifier for the build run (e.g., `1`)

For example:

```bash
jf pip install -r requirements.txt --build-name=my-python-app --build-number=1
```

#### Install a Single Package

```bash
jf pip install <package-name>
```

For example:

```bash
jf pip install requests
```

***

## Recording All Dependencies

JFrog CLI records installed packages as build-info dependencies. The recorded dependencies are packages installed during the `jf pip install` command execution. When running inside a Python environment that already has some packages installed, those packages will not be included in the build-info because they were not originally installed by JFrog CLI. A warning message will appear in the log.

**How to include all packages in the build-info:**

The details of all installed packages are cached by `jf pip install` in `.jfrog/projects/deps.cache.json`, located under the root of the project. JFrog CLI uses this cache for including previously installed packages in the build-info.

If the Python environment had packages installed before the first execution of the install command, those packages will be missing from the cache. Running the install command with both the `--no-cache-dir` and `--force-reinstall` pip options will re-download and install these packages, adding them to the build-info and cache. It is also recommended to run the command from inside a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/).

## Important Notes

* **pip commands**: All standard pip arguments work (`install`, `install -r requirements.txt`, `freeze`, and others).
* **Build-info**: Use `--build-name` and `--build-number` to collect installed package info, then publish with `jf rt build-publish`.
* **Publishing**: `jf pip` is for **installing** packages. To **publish** Python packages to Artifactory, use [`jf twine`](jf-twine.md).

## Platform Notes

* **Windows:** The `.pypirc` configuration file is located at `%USERPROFILE%\.pypirc`. On macOS/Linux it is at `~/.pypirc`.
* **Virtual environments:** On Windows, activate with `.\venv\Scripts\activate`. On macOS/Linux, use `source venv/bin/activate`.
* **pip vs pip3:** On systems where Python 2 and 3 coexist, use `pip3` to ensure the correct version is used.

## CI/CD Example (GitHub Actions)

```yaml
# .github/workflows/build.yml
steps:
  - uses: actions/checkout@v4
  - name: Setup JFrog CLI
    uses: jfrog/setup-jfrog-cli@v4
    env:
      JF_URL: ${{ vars.JF_URL }}
      JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
  - name: Setup Python
    uses: actions/setup-python@v5
    with:
      python-version: '3.12'
  - name: Configure pip
    run: jf pip-config --server-id-resolve=setup-jfrog-cli-server --repo-resolve=pypi-virtual
  - name: Install dependencies
    run: jf pip install -r requirements.txt --build-name=my-python-app --build-number=${{ github.run_number }}
  - name: Publish build info
    run: jf rt build-publish my-python-app ${{ github.run_number }}
```

## Troubleshooting

| Symptom                              | Cause                                                 | Fix                                                                                                          |
| ------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `no config file was found`           | `jf pip-config` was not run                           | Run `jf pip-config` in the project directory                                                                 |
| 404 on `jf pip install`              | Resolution repository does not exist or name is wrong | Verify the repo name matches an existing PyPI virtual repository in Artifactory                              |
| 401 / 403 errors                     | Invalid credentials or insufficient permissions       | Re-run `jf config add` with a valid access token; check repo permissions                                     |
| Build-info missing some dependencies | Packages were installed before JFrog CLI was used     | Run `jf pip install --no-cache-dir --force-reinstall -r requirements.txt` inside a clean virtual environment |
| `pip` not found                      | Wrong Python/pip version or not in PATH               | Use `pip3` or ensure the correct Python environment is active                                                |
| SSL certificate errors               | Corporate proxy or self-signed certificates           | Use `--insecure-tls` on `jf config add`, or configure your CA bundle                                         |

**Enable debug logging:** `export JFROG_CLI_LOG_LEVEL=DEBUG`

<br />

## Related Topics

* [Build Tools Overview](/artifactory/docs/build-tool-commands) — Capabilities matrix and tool reference
* [Native Mode](/artifactory/docs/native-mode) — Supported packages with Native Mode