Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Python Virtualenv Powered by Docker

Project description


Python versions Pypi Travis build License

Notice: This project is currently in alpha stage

pydockenv is a library that aims to give the same experience of having a virtual environment, but backed by Docker! The idea is to make the usage of Docker completely hidden so that even non-expert Docker users can leverage the advantages provided by using it as the underlying engine.


To install pydockenv run the following:

pip install --user pydockenv

To avoid conflicts this installs pydockenv to the Python user install directory. In order to run the pydockenv binary, you will need to have that directory in your PATH. You can do this by running these lines:

export PY_USER_BIN=$(python -c 'import site; print(site.USER_BASE + "/bin")')

pydockenv supports only python >=3.6 at the moment and will use the python binary. In case your system has another version installed, you can use a different interpreter by specifying its path through the PYDOCKENV_INTERPRETER environment variable:

PYDOCKENV_INTERPRETER=path/to/binary pydockenv [...]
# or
export PYDOCKENV_INTERPRETER=path/to/binary
pydockenv [...]


I assume that everybody landing here knows the great advantages that virtual environment brings. The reason I've started this project is that Docker provides even better isolation from the underlying system, and brings the advantage of being really portable across different systems.

In my personal experience sometimes is difficult to replicate the same local virtual environment, and eventually save it and share it with somebody else, especially if the one you want to share the environment with runs, for example, a different operating system.

Using Docker as the engine of the virtual environment makes the environment itself isolated, easily sharable, and also eventually ready-to-be-deployed given that it is still a Docker container.


The installation will provide you with the pydockenv binary that let you create, save, load an environment and handle its dependencies.

Let's start by creating an environment!

Let's create the environment!

To create an environment run the following command:

pydockenv create --name=<env name> <project directory>

For example, if you are in the root of a project named awesome-project this could be:

pydockenv create --name=awesome-project .

This will create a Docker container with the latest Python version installed! If you want to create an environment with a specific Python version you only just need to add the --version=<python version> to the previous command:

pydockenv create --name=awesome-project --version=3.6 .

As you may have noticed, to create the environment you have to set a project directory. This means that everything that is not inside the project directory is completely invisible to the environment. For example, you cannot access a Python script that resides outside your project directory. See the details in the Advanced section.

Creating an environment from a *.toml file

Alternatively, you can use a *.toml file describing your environment. This is analogous to having a requirements.txt file. This file describes both the dependencies and the python version to use, for example:

name = "awesome-project"
python = "3.7.4"

requests = ">=2.22.0"

All the version specifiers described in PEP 440 are supported.

Let's say that this is the content of a pydockenv.toml file in the current working directory. You can then create the environment as follows:

pydockenv create --file=pydockenv.toml <project directory>

You can eventually create it with a different name still using the --name flag:

pydockenv create --file=pydockenv.toml --name=another-awesome-project <project directory>

The *.toml file can be automatically created from an already existing environment by running:

pydockenv export --output=pydockenv.toml

Activation and packages installation

Now you can activate your newly created environment!

source pydockenv activate <env name>

You can verify that the environment has been successfully activated by also running

pydockenv status

With pydockenv you can install Python packages simply by using the install command:

pydockenv install <package>

such as:

pydockenv install requests

and that's it! You can list all your environments and all the packages installed in the currently active environment with the following commands respectively:

# list all environments
pydockenv list-environments
# list packages installed in current environment
pydockenv list-packages

Running the Python shell

To run the Python shell you simply have to run the shell command:

pydockenv shell

and the shell with the correct version of Python will start.

Running a sample application

Running a Python script is very easy as well. Instead of running it as:

python arg1 arg2 ...

you just have to prefix it with pydockenv run as follows:

pydockenv run python arg1 arg2 ...

And that's it! You're now ready to go! For a more complete overview of the commands see the Examples and the Commands reference sections.


Here are some examples that are available in the examples directory to show more practically how to use pydockenv.

Hello World!

File: examples/

This first example just shows how different environments work. The script simply prints the "Hello World!" string followed by the Python version being used. You can run this on different environments and see how the output changes. See the following gif.


File: examples/

This second example shows how you can install external packages and run Python scripts by passing arguments as you would do normally. See the following gif.

Flask web app

File: examples/

This third example shows how you can run a Flask web application. This example is important as it shows some caveats that make the experience of using pydockenv not completely identical to using a local environment. Given the environment runs inside a container, the host must be and not localhost, and the port being used must be told to pydockenv using the -p/--port flag of the run command. See the following gif.

Commands reference


Environment handling

Packages handling





To setup you environment to develop pydockenv run the followings:

  1. Clone the repository where you prefer:
git clone <dir>
  1. Enter in the project root directory:
cd <dir>
  1. Install pydockenv in editable mode in another path:
export PYTHONPATH=<prefix>/lib/python3.7/site-packages
mkdir -p <prefix>/lib/python3.7/site-packages
pip install --prefix <prefix> -e .

I personally use ~/.local-dev as <prefix>.

  1. Rename pydockvenv into dev-pydockenv or whatever you want:
mv <prefix>/bin/{,dev-}pydockenv
  1. Add <prefix>/bin to you $PATH:
export PATH=<prefix>/bin:$PATH

Now you have dev-pydockenv that runs the development version of pydockenv!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pydockenv, version 0.5.0
Filename, size File type Python version Upload date Hashes
Filename, size pydockenv-0.5.0-py3-none-any.whl (19.9 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pydockenv-0.5.0.tar.gz (15.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page