docs/faq.md
This document answers common questions about Pipenv, its usage, and how it compares to other tools.
Pipenv is a Python dependency management tool that combines pip, virtualenv, and Pipfile into a single unified interface. It creates and manages virtual environments for your projects automatically, while also maintaining a Pipfile for package requirements and a Pipfile.lock for deterministic builds.
While pip is excellent for installing Python packages, Pipenv offers several advantages:
Pipfile.lock with exact versions and hashes for deterministic builds.env filesBoth Pipenv and Poetry are modern Python dependency management tools, but they have different focuses:
Pipenv:
Poetry:
Choose Pipenv if you want a straightforward tool for application development that integrates well with the existing Python ecosystem. Choose Poetry if you're developing libraries or need its additional packaging features.
Yes, Pipenv is actively maintained by the Python Packaging Authority (PyPA) and a community of contributors. You can check the GitHub repository for recent activity.
pipenv command after installation?If you installed Pipenv with pip install --user pipenv, the executable might not be in your PATH. You need to add the user site-packages binary directory to your PATH:
On Linux/macOS:
# Find the user base binary directory
$ python -m site --user-base
/home/username/.local
# Add to PATH (add this to your ~/.bashrc or ~/.zshrc)
$ export PATH="$HOME/.local/bin:$PATH"
On Windows:
# Find the user site-packages directory
> python -m site --user-site
C:\Users\Username\AppData\Roaming\Python\Python39\site-packages
# Add the Scripts directory to PATH (replace 'site-packages' with 'Scripts')
# Add C:\Users\Username\AppData\Roaming\Python\Python39\Scripts to your PATH
It's recommended to install Pipenv per user with pip install --user pipenv. This avoids potential permission issues and conflicts with system packages.
Yes, you can specify which Python version to use when creating a virtual environment:
$ pipenv --python 3.9
You can also specify the Python version in your Pipfile:
[requires]
python_version = "3.9"
By default, Pipenv stores virtual environments in a centralized location:
~/.local/share/virtualenvs/%USERPROFILE%\.virtualenvs\The virtual environment name is derived from the project directory name and a hash of the full path.
Set the PIPENV_VENV_IN_PROJECT environment variable:
$ export PIPENV_VENV_IN_PROJECT=1
$ pipenv install
This creates a .venv directory in your project.
$ pipenv shell
This spawns a new shell with the virtual environment activated. You can exit this shell with exit or Ctrl+D.
Alternatively, you can run commands in the virtual environment without activating it:
$ pipenv run python script.py
pipenv install and pipenv sync?pipenv install: Installs packages specified in the Pipfile, updates the Pipfile.lock if necessary, and installs the packages.pipenv sync: Installs packages exactly as specified in the Pipfile.lock without updating it.Use pipenv install during development when you want to add or update packages. Use pipenv sync in production or CI/CD pipelines when you want to ensure exact package versions are installed.
pipenv update and pipenv upgrade?pipenv update: Updates the lock file and installs the updated packages.pipenv upgrade: Updates only the lock file without installing the packages.# Install a package as a development dependency
$ pipenv install pytest --dev
# Install all dependencies including development dependencies
$ pipenv install --dev
$ pipenv requirements > requirements.txt
To include development dependencies:
$ pipenv requirements --dev > requirements.txt
Yes, you should commit both files:
This message appears when your Pipfile has been modified since the last time Pipfile.lock was generated. Run pipenv lock to update the lock file.
No, you should never manually edit Pipfile.lock. It's a machine-generated file that contains precise information about your dependencies. Use Pipenv commands to modify it.
Pipenv supports various version specifiers:
[packages]
requests = "*" # Any version
flask = "==2.0.1" # Exact version
django = ">=3.2.0" # Minimum version
numpy = ">=1.20.0,<2.0.0" # Version range
pandas = "~=1.3.0" # Compatible release (>=1.3.0,<1.4.0)
$ pipenv install -e git+https://github.com/requests/requests.git#egg=requests
Or in your Pipfile:
[packages]
requests = {git = "https://github.com/requests/requests.git", ref = "master"}
$ pipenv install -e ./path/to/package
Or in your Pipfile:
[packages]
my-package = {path = "./path/to/package", editable = true}
If you encounter dependency conflicts:
pipenv graph to visualize dependencies and identify conflictspipenv lock --clear to clear the cache and try againDependency resolution can be computationally intensive, especially for projects with many dependencies. To improve performance:
PIPENV_SKIP_LOCK=1pipenv sync instead of pipenv install when you just need to install packages# Skip lock file generation during development
$ export PIPENV_SKIP_LOCK=1
$ pipenv install package-name
# Use a local PyPI mirror
$ export PIPENV_PYPI_MIRROR=https://pypi.tuna.tsinghua.edu.cn/simple
# Clear the cache if it's gotten large
$ pipenv lock --clear
Create a .env file in your project directory:
# .env
DEBUG=True
DATABASE_URL=sqlite:///dev.db
Pipenv automatically loads these variables when you use pipenv shell or pipenv run.
Pipenv can be configured through environment variables. For example:
# Store virtualenvs in the project directory
$ export PIPENV_VENV_IN_PROJECT=1
# Skip lock file generation during development
$ export PIPENV_SKIP_LOCK=1
# Use a custom Pipfile location
$ export PIPENV_PIPFILE=/path/to/Pipfile
See the Configuration page for a complete list of options.
Pipenv looks for a Pipfile in the current directory and parent directories. Make sure you're in the correct directory or specify the Pipfile location:
$ export PIPENV_PIPFILE=/path/to/Pipfile
This usually means the package isn't installed in your virtual environment. Try:
$ pipenv install X
If the package is already in your Pipfile, try:
$ pipenv update X
If virtualenv creation fails:
PIPENV_VENV_IN_PROJECT=1pipenv --python 3.9pipenv --supportTo start fresh:
# Remove the virtual environment
$ pipenv --rm
# Clear the cache
$ pipenv lock --clear
# Create a new environment
$ pipenv install
In your Dockerfile:
FROM python:3.9-slim
WORKDIR /app
# Copy dependency files
COPY Pipfile Pipfile.lock ./
# Install pipenv and dependencies
RUN pip install pipenv && \
pipenv install --system --deploy
# Copy application code
COPY . .
# Run the application
CMD ["python", "app.py"]
Find your virtualenv path:
$ pipenv --venv
In VS Code, press Ctrl+Shift+P and select "Python: Select Interpreter"
Choose "Enter interpreter path..." and paste the path to the Python executable in your virtualenv (add /bin/python on Linux/macOS or \Scripts\python.exe on Windows to the path)
Find your virtualenv path:
$ pipenv --venv
In PyCharm, go to Settings → Project → Python Interpreter
Click the gear icon → Add → Existing Environment
Browse to the Python executable in your virtualenv
In your CI/CD configuration:
# Example GitHub Actions workflow
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.9'
- name: Install pipenv
run: pip install pipenv
- name: Verify Pipfile.lock
run: pipenv verify
- name: Install dependencies
run: pipenv install --dev
- name: Run tests
run: pipenv run pytest
Pipenv enhances security in several ways:
pipenv scan checks for known security vulnerabilities$ pipenv scan
This command checks your dependencies against the PyUp Safety database of known vulnerabilities.
While Pipenv is primarily designed for application development, you can use it for library development. However, you'll still need to maintain a setup.py or pyproject.toml file for distribution.
For library development, you might consider Poetry, which has better support for building and publishing packages.
See the Contributing Guide for information on how to contribute to Pipenv.