How to set up Python virtual environments in Replit

When you create a Python Repl, Replit automatically sets up a virtual environment in a hidden directory. This venv is activated by default whenever you use the Shell or Run button, so pip install commands install packages into the project's isolated environment rather than the system Python. You can verify this by running which python in the Shell, which should point to a path inside your project rather than /usr/bin/python. This automatic setup means you do not need to run python -m venv or activate scripts like you would locally.

1# Run these in the Shell to inspect your environment
2which python
3python --version
4pip list

The simplest way to add Python packages in Replit is pip install in the Shell. Replit also auto-installs packages when it detects import statements in your code, but this automatic installation can be unreliable for packages with complex names or optional dependencies. Always verify installation by importing the package in the Shell. For reproducibility, create a requirements.txt file so your dependencies are documented and can be reinstalled if the environment resets.

1# Install a single package
2pip install requests
3
4# Install from a requirements file
5pip install -r requirements.txt
6
7# Create a requirements file from current environment
8pip freeze > requirements.txt
9
10# Install a specific version
11pip install flask==3.0.0

Poetry is a more robust dependency manager that creates a poetry.lock file for deterministic installs. Replit supports poetry natively. If your project already has a pyproject.toml file, poetry is likely already configured. Poetry resolves dependency conflicts automatically and separates development dependencies from production ones. Use poetry add to install packages and poetry install to restore the environment from the lock file.

1# Install poetry if not already available
2pip install poetry
3
4# Initialize a new poetry project
5poetry init --no-interaction
6
7# Add a package
8poetry add requests
9
10# Add a dev-only package
11poetry add --group dev pytest
12
13# Install all dependencies from lock file
14poetry install
15
16# Run a script through poetry's environment
17poetry run python main.py

Replit uses Nix for system-level configuration, including the Python version. To switch Python versions, you need to modify the replit.nix file (show hidden files first). Change the Python package reference to the version you need. After saving, run exit in the Shell to reload the Nix environment. Available Python packages include pkgs.python310, pkgs.python311, and pkgs.python312. Note that changing the Python version may require reinstalling your pip packages.

1# replit.nix — change the Python version here
2{ pkgs }: {
3  deps = [
4    pkgs.python311
5    pkgs.python311Packages.pip
6  ];
7}

Some Python packages require system-level libraries that are not included in Replit's default environment. For example, Pillow needs image processing libraries, and psycopg2 needs PostgreSQL client libraries. Add these system dependencies to replit.nix alongside your Python packages. Search for available packages at search.nixos.org/packages. This is the most common cause of 'failed building wheel' errors during pip install.

1# replit.nix with system dependencies for common packages
2{ pkgs }: {
3  deps = [
4    pkgs.python311
5    pkgs.python311Packages.pip
6    pkgs.zlib
7    pkgs.libjpeg
8    pkgs.libpng
9    pkgs.postgresql
10  ];
11}

The most frequent Python environment errors in Replit are ModuleNotFoundError (package not installed or wrong environment), version conflicts between packages, and 'failed building wheel' (missing system dependencies). When you encounter these, first verify your environment with which python and pip list. If packages seem to disappear, the virtual environment may have been corrupted. The nuclear option is deleting the .pythonlibs directory and reinstalling everything from requirements.txt.

1# Diagnostic commands for environment issues
2which python
3python --version
4pip list
5pip check  # verify no broken dependencies
6
7# Nuclear reset: delete and recreate the environment
8rm -rf .pythonlibs
9pip install -r requirements.txt